1 # winsockprt.cif

     2 #

     3 # Copyright (c) 2007-2010 Accenture. All rights reserved.

     4 # This component and the accompanying materials are made available

     5 # under the terms of the "Eclipse Public License v1.0"

     6 # which accompanies this distribution, and is available

     7 # at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 #

     9 # Initial Contributors:

    10 # Accenture - Initial contribution

    11 #

    12 

    13 __END__

    14 

    15 =head1 winsockprt

    16 

    17 =head2 Introduction

    18 

    19 C<winsockprt> is a Symbian OS network protocol module (a plug-in to ESock) that allows Symbian OS sockets to communicate via underlying WinSock sockets.

    20 

    21 There are various means of providing the Symbian OS emulator with a network connection (including WinTAP and NT-RAS). In the most part these other technologies are preferable to C<winsockprt> because they use the real Symbian TCP/IP stack, and so provide a more faithful emulation. However, they also tend to be more complex to configure. By contrast, C<winsockprt> is enabled with a single command and needs no further configuration.

    22 

    23 =head2 Installation

    24 

    25 Beyond building F<fshell> for your development environment, there is no further installation necessary.

    26 

    27 =head2 Usage

    28 

    29 By default C<winsockprt> is disabled. To enable it, type:

    30 

    31   wsp enable

    32 

    33 or

    34 

    35   wsp e

    36 

    37 Once it is enabled, any attempt by Symbian code to open a socket (or resolver) on the implicit connection (i.e. without using C<RConnection>) will result in C<winsockprt> interacting with the WinSock library to provide a connection.

    38 

    39 To disable C<winsockprt> and go back to using the Symbian TCP/IP stack, type:

    40 

    41   wsp disable

    42 

    43 or

    44 

    45   wsp d

    46 

    47 To see the current state of the C<winsockprt>, type:

    48 

    49   wsp status

    50 

    51 or

    52 

    53   wsp s

    54 

    55 =head2 Caveats

    56 

    57 No attempt is made to intercept the C<RConnection> API, which means that code that uses this will continue to attempt to establish a real connection. If this succeeds, then any sockets attached to the connection will again be routed through the WinSock library. However, if it was possible to establish a real connection, then there probably isn't much point in using C<winsockprt> - better to disable it and go back to using the real TCP/IP stack.

    58 

    59 =head2 Explicit Usage

    60 

    61 It is actually still possible to open C<winsockprt> sockets even when the module is disabled. Disabled only means that the module isn't taking the place of the Symbian TCP/IP stack. Whether disabled or not, C<winsockprt> always registers the following protocols with ESock and makes them available to clients:

    62 

    63   KProtocolWinsockTcp

    64   KProtocolWinsockUdp

    65 

    66 These are defined in F<\epoc32\include\winsockprt.h> and allow software to explicitly use WinSock sockets along side normal Symbian sockets. This facility can be used by L<rcons|rcons> to provide remote console via WinSock on the emulator without distrupting other TCP/IP clients.

    67 

    68 =head2 Future Development

    69 

    70 Old versions of C<winsockprt> used to replace various parts of the Symbian networking sub-system in order to try to convince clients that a suitable connection is available. In the multi-homed world of modern Symbian OS releases this behaviour is probably not appropriate. Instead therefore, to use C<winsockprt> from via software the opens an explicit C<RConnection> suitable IAP and Network entries will need to be present in the CommDb. There is a Null Agent (C<nullagt>) that could be used to pretend to establish a connection. However, at the time of writing, there is nothing equivalent to a Null NIF that would also be needed to create a truely fake connection. It might be worth writing such a thing is this limitation is frequently hit.

    71 

    72 =head1 See Also

    73 

    74 L<rcons|rcons>

    75 

    76 =head1 Copyright

    77 

    78 Copyright (c) 2005-2010 Accenture. All rights reserved.

    79 

    80 =cut