/*
* Copyright (c) 2009 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.
*
* Contributors:
*
* Description:
*
*/
HOWTO for Wins Ethernet Driver

0. Pre-requisities
The implementation of Wins Ethernet driver makes use of packet capturing library: 
WinPcap, Release 2.2. This software sets the network card of the PC, on which Epoc 
Emulator is working, into so called promiscuous mode. The user must be confident that 
the environment she/he works in doesnt forbid such settings. The quickest way 
to ensure about it is to contact network administrator.


1. Trouble Shooting
The following problems may occur when attempting to use WINS version of Ethernet driver:
* Network application doesnt send nor receive any packets: two potential reasons:
  - bad settings in CommDB - refer to point 4
  - Wpcap not installed - refer to point 2

* A panic is raised of category: 'D32ETHER' with one of the following reasons:
   1	meaning: bad MAC address in ini file or entry for it missing or ini file missing
   2	meaning: entry for network interface name missing in ini file or ini file missing
   3	meaning: Wpcap couldn't be initialised - potentially not installed or name 
	of network interface in .ini file wrong
Panics occur if system is not configured properly, remedy can be found in notes below.

* Wpcap error may occur - refer to http://winpcap.polito.it/misc/changelog.htm 
  for advice how to fix the problem (this will require usually upgrading WinPcap 
  package on user' machine).


2. Wpcap
Wpcap must be installed on a machine that wishes to use driver. Installation is simple: 
WinPcap.exe (located in: \epoc32\tools)
should be run and then instructions should be followed. 
If user has already Wpcap installed on his workstation then should try to use 
Ethernet driver with this version. In case when it fails he must uninstall existing 
Wpcap and install the one from Epoc directory mentioned above.


3. Netcards
When Wpcap is already installed, a program called Netcards.exe should be run. 
It can be found in \epoc32\tools. 
(Note: Netcards uses Wpcap so the latter must be installed first). 
It will request user to select network card. Netcards writes a few entries 
into \epoc32\data\ethernet.ini file which are read by Epoc Emulator at startup 
(ensure that \epoc32\data directory exists). In particular MAC address value for use 
by Emulator is determined by the entry named 'ETHER_MAC' (it is recommended that 
network administrator was aware of the value of MAC address written there and authorise 
it if necessary; according to local conditions any other value preferred 
by administrator can be written manually instead of the value written by Netcards). 
Ethernet driver for WINS was originally 
designed for use in Techview environment which uses ethernet.ini file. Other environments 
(like Quartz) may use different .ini file (e.g. \epoc32\data\quartz.ini). A user can 
still run Ethernet module in these environments provided that .ini files appropriate 
for these environments contain entries written by netcards.exe to ethernet.ini - user can 
simply copy them - they are easy to recognise as they begin with ETHER_ prefix .


4. CommDB
CommDB settings should indicate use of the NIF: ethint.nif and the agent: nullagt.agt. 
In current release of Epoc Networking software, data in the database are written by program 
called ced.exe, which takes wanted settings from text file: ced.cfg.
Example settings to be put in this file are shown below. In the example it is assumed 
that IP address and network mask will be acquired by DHCP protocol:

############################################################
## LANBearer
## 
[LANBearer]
ADD_SECTION
# COMMDB_ID = 1
	Name=Wins Ethernet
	Agent=nullagt.agt
	IfName=ethint
	LDDFilename=enet
	LDDName=Ethernet
	PDDFilename=ethernet
	PDDName=Ethernet.Wins
	PacketDriverName=EtherPkt.drv
	LastSocketActivityTimeout=-1
	LastSessionClosedTimeout=-1
	LastSocketClosedTimeout=-1
	FIELD_COUNT=8
END_ADD

ADD_SECTION
# COMMDB_ID = 2
	Name=Assabet on-board Ethernet
	Agent=nullagt.agt
	IfName=ethint
	LDDFilename=enet
	LDDName=Ethernet
	PDDFilename=ethernet
	PDDName=Ethernet.Assabet
	PacketDriverName=EtherPkt.drv
	LastSocketActivityTimeout=-1
	LastSessionClosedTimeout=-1
	LastSocketClosedTimeout=-1
	FIELD_COUNT=8
END_ADD

############################################################
## LANService
## 
[LANService]

ADD_SECTION
# COMMDB_ID = 1
	Name=Ethernet
	#IfNetworks=ip,ip6
	IfNetworks=ip
	IpNetMask=0.0.0.0
	IpGateway=0.0.0.0
	IpAddrFromServer=TRUE
	IpAddr=0.0.0.0
	IpDNSAddrFromServer=TRUE
	IpNameServer1=0.0.0.0
	IpNameServer2=0.0.0.0
	FIELD_COUNT=9
END_ADD


############################################################
## IAP
## 
[IAP]
ADD_SECTION
# COMMDB_ID = 1
	Name=Ethernet IAP
	IAPService=1
	IAPServiceType=LANService
	IAPBearer=1
	IAPBearerType=LANBearer
	IAPNetwork=1
	IAPNetworkWeighting=0
	Location=2
	FIELD_COUNT=8
END_ADD

ADD_SECTION
# COMMDB_ID = 2
	Name=NT RAS with Null Modem
	IAPService=2
	IAPServiceType=DialOutISP
	IAPBearer=2
	IAPBearerType=ModemBearer
	IAPNetwork=1
	IAPNetworkWeighting=0
	Location=2
	FIELD_COUNT=8
END_ADD

############################################################
## ConnectionPreferences
## 
[ConnectionPreferences]


ADD_SECTION
	Ranking=0
	Direction=OUTGOING
	DialogPref=PROMPT
	BearerSet=LAN
	#IAP=Ethernet IAP
	IAP=1
	FIELD_COUNT=5
END_ADD

ADD_SECTION
	Ranking=1
	Direction=OUTGOING
	DialogPref=DONOTPROMPT
	BearerSet=LAN
#IAP=Ethernet IAP
	IAP=1
	FIELD_COUNT=5
END_ADD

 
