Symbian3/SDK/Source/GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <concept id="GUID-4ADD8234-4AFD-4E80-94A4-AC018FE83276" xml:lang="en"><title>Differences
       
    13 between OSS and Symbian GLib</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <p>The three areas of difference between the way GLib is implemented in Symbian
       
    15 platform and in OSS are as follows: </p>
       
    16 <ul>
       
    17 <li><p>Memory allocation</p></li>
       
    18 <li><p>Spawn APIs</p></li>
       
    19 <li><p>Libgmodule APIs </p></li>
       
    20 </ul>
       
    21 <section id="GUID-DFAD39D6-BA92-4293-B5EC-97077CE1FC1A-GENID-1-6-1-10-1-1-7-1-6-1-4-1-3-3">       <title>Memory
       
    22 allocation</title>       <p>The Symbian GLib implementation does not follow
       
    23 the default OSS behavior. The default OSS behavior is such that in the event
       
    24 of a memory allocation failure the application, using <codeph>g_malloc()</codeph> and
       
    25 not <codeph>g_try_malloc()</codeph>, will call <codeph>abort()</codeph> and
       
    26 thus terminate the application.  </p><p>The Symbian implementation, on the
       
    27 other hand will return NULL and not terminate the application in the event
       
    28 of a memory allocation failure. Thus, it is the application’s responsibility
       
    29 to check if the memory allocation failed due to the needed tasks.</p><p>Generally,
       
    30 all the application code written using GLib does not perform memory allocation
       
    31 failure checks. Hence, for Symbian GLib it is the application programmer's
       
    32 responsibility to check for memory allocation failures.  </p>     </section>
       
    33 <section id="GUID-DFAD39D6-BA92-4293-B5EC-97077CE1FC1A-GENID-1-6-1-10-1-1-7-1-6-1-4-1-3-4">       <title>Spawn
       
    34 APIs</title>       <p>GLib has a set of APIs for process spawning. Since Symbian
       
    35 platform does not support the <codeph>fork()</codeph> and <codeph>exec()</codeph> APIs,
       
    36 the <codeph>g_spawn*</codeph> APIs have limitations in their functionality.
       
    37 The limitations are explained per API in detail below.</p><p><b><codeph>g_spawn_async_with_pipes</codeph></b></p><p>The
       
    38 signature of this API is:</p><codeblock xml:space="preserve">gboolean g_spawn_async_with_pipes (
       
    39     const gchar *working_directoy,
       
    40     gchar **argv,
       
    41     gchar **envp,
       
    42     GSpawnFlags flags, 			
       
    43     GSpawnChildSetupFunc child_setup, 			
       
    44     gpointer user_data, 			
       
    45     GPid *child_pid, 			
       
    46     gint  *standard_input, 			
       
    47     gint *standard_output, 			
       
    48     gint *standard_error, 			
       
    49     GError **error); </codeblock><p>This API executes the program asynchronously:
       
    50 that is, the caller does not block for the spawned process to complete. The
       
    51 setting of the following parameters does not have any effect in Symbian GLib:</p><ul>
       
    52 <li><p><codeph>working_directory</codeph></p></li>
       
    53 <li><p><codeph>envp</codeph></p></li>
       
    54 </ul><p>If a value other than NULL is passed for <codeph>standard_input</codeph>, <codeph>standard_ouput</codeph>,
       
    55 or <codeph>standard_error</codeph>, the value at the location is set to -1.</p><p><b><codeph>g_spawn_async</codeph></b></p><p>The
       
    56 signature of the API is:</p><codeblock xml:space="preserve">gboolean g_spawn_async (
       
    57     const gchar *working_directory, 	 	  
       
    58     gchar **argv, 		  
       
    59     gchar **envp, 		  
       
    60     GSpawnFlags flags, 		  
       
    61     GSpawnChildSetupFunc child_setup, 		  
       
    62     gpointer user_data, 		  
       
    63     GPid *child_pid, 		  
       
    64     GError **error); </codeblock><p>This API calls <codeph>g_spawn_async_with_pipes</codeph> without
       
    65 any pipes. The setting of the following parameters does not have any effect
       
    66 in Symbian GLib:</p><ul>
       
    67 <li><p><codeph>working_directory</codeph></p></li>
       
    68 <li><p><codeph>envp</codeph></p></li>
       
    69 </ul><p><b><codeph>g_spawn_sync</codeph></b></p><p>The signature of the API
       
    70 is:</p><codeblock xml:space="preserve">gboolean g_spawn_sync(
       
    71     const gchar *working_directory, 	 	
       
    72     gchar **argv, 		
       
    73     gchar **envp, 		
       
    74     GSpawnFlags flags, 		
       
    75     GSpawnChildSetupFunc child_setup, 		
       
    76     gpointer user_data, 		
       
    77     gchar **standard_output, 		
       
    78     gchar **standard_error, 		
       
    79     gint *exit_status, 		
       
    80     GError **error); </codeblock><p>This API executes the program synchronously:
       
    81 that is, the calling process waits for the spawned process to complete before
       
    82 returning. The setting of the following parameters does not have any effect
       
    83 on Symbian GLib:  </p><ul>
       
    84 <li><p><codeph>working_directory</codeph></p></li>
       
    85 <li><p><codeph>envp</codeph></p></li>
       
    86 </ul><p>If a value other than NULL is passed for<codeph> standard_output</codeph> or <codeph>standard_error</codeph>,
       
    87 the value at the location is set to -1. </p><p><b><codeph>g_spawn_command_line_sync</codeph></b></p><p>The
       
    88 signature of the API is:</p><codeblock xml:space="preserve">gboolean g_spawn_command_line_sync(
       
    89     const gchar *command_line, 
       
    90     gchar **standard_output, 
       
    91     gchar **standard_error, 
       
    92     gint *exit_status, 
       
    93     GError **error);  </codeblock><p>This API is a simple version of <codeph>g_spawn_sync</codeph> in
       
    94 which there are fewer number of parameters involved, and it takes a command
       
    95 line instead.</p><p>If a value other than NULL is passed for <codeph>standard_output</codeph> or <codeph>standard_error</codeph>,
       
    96 the value at the location is set to -1.</p><p>In many spawn APIs a variable
       
    97 of type <codeph>GSpawnFlags</codeph> is passed. The following flags have no
       
    98 effect:</p><ul>
       
    99 <li><p><codeph>G_SPAWN_LEAVE_DESCRIPTORS_OPEN</codeph></p></li>
       
   100 <li><p><codeph>G_SPAWN_STDOUT_TO_DEV_NULL</codeph></p></li>
       
   101 <li><p><codeph>G_SPAWN_STDERR_TO_DEV_NULL</codeph></p></li>
       
   102 <li><p><codeph>G_SPAWN_CHILD_INHERITS_STDIN</codeph></p></li>
       
   103 </ul>     </section>
       
   104 <section id="GUID-4B68F695-1BDB-4AA0-B77A-7F808A157E7A"><title>Libgmodule
       
   105 APIs</title><p>Libgmodule has APIs that provide a portable method for dynamically
       
   106 loading 'plug-ins' or, in other words, DLLs. There are some deviations in
       
   107 the <codeph>libgmodule</codeph> APIs on Symbian platform as compared to the
       
   108 OSS behavior. The APIs with their limitations are explained in detail below.</p><ul>
       
   109 <li><p><b><codeph>g_module_open</codeph></b>: The signature of the API is:</p><codeblock xml:space="preserve">GModule *g_module_open (const gchar *file_name, GModuleFlags flags);</codeblock><p>This API is used to open a module. The default OSS behavior when file_name
       
   110 is passed as NULL such that it obtains a <codeph>GModule</codeph> representing
       
   111 the main program. In Symbian GLib, NULL is returned instead. Of all the <codeph>GModuleFlags</codeph> only <codeph>G_MODULE_BIND_LOCAL</codeph> is
       
   112 honored. If the user passes any other flags, the module is still opened using
       
   113 the flag <codeph>G_MODULE_BIND_LOCAL</codeph>. </p></li>
       
   114 <li><p><b><codeph>g_module_symbol</codeph></b>: The signature of the API is:</p><codeblock xml:space="preserve">gboolean g_module_symbol (GModule *module, const gchar *symbol_name, gpointer *symbol);</codeblock><p>This API gets the symbol from the <codeph>GModule</codeph> opened using <codeph>g_module_open</codeph>.
       
   115 In OSS, <codeph>symbol_name</codeph> is the name of the symbol that needs
       
   116 to be queried from the <codeph>GModule</codeph>. In Symbian platform, the
       
   117 ordinal number (passed as a string) of the symbol name must be passed and
       
   118 not the symbol name.</p></li>
       
   119 </ul><p>See also <xref href="GUID-01E7AE98-024C-4119-87D0-5BB9D53DA119.dita">Introduction
       
   120 to libgmodule</xref> for more details about <codeph>libgmodule</codeph>. </p></section>
       
   121 </conbody></concept>