LABORATORIO DE TELEMATICA Guia de Referencia del API...

Ingeniería de Telecomunicación. 3er Curso

ÏÏTT Universidad Carlos III de Madrid Dpto. de Ingeniería Telemática

LABORATORIO DE TELEMATICA

Guia de Referencia del API NEPAL

Prof. Dr. José Ignacio Moreno Novella

Referencia del API Nepal Laboratorio de Telemática

Índice:1. Introducción a la librería NEPAL ............................................................................. 42. Características de NEPAL......................................................................................... 6

� Múltiples accesos a múltiples tarjetas................................................................ 6� Tramas reflejadas ............................................................................................... 6� Sincronismo en las operaciones de Entrada/Salida............................................ 7� Filtros ................................................................................................................. 7

3. Guia de Programación de NEPAL ............................................................................ 8� Instrucciones generales de uso........................................................................... 8� Envío de tramas.................................................................................................. 9� Recepción de tramas ........................................................................................ 10

4. Referencia del API NEPAL .................................................................................... 11� Descripción general del interfaz de NEPAL.................................................... 11� Tipos y estructuras de datos............................................................................. 13� Constantes ........................................................................................................ 13

5. Descripción detallada del Interfaz de NEPAL ........................................................ 145.1 Apertura / Cierre del adaptador............................................................................. 14

� NepalOpenAdapter .......................................................................................... 14� NepalCloseAdapter .......................................................................................... 15

5.2 Envío de tramas..................................................................................................... 16� NepalSendPacket ............................................................................................. 16

5.3 Recepción de tramas ............................................................................................. 18� NepalReadPacket ............................................................................................. 18� NepalCheckForData......................................................................................... 20

5.4 Control y solicitud ................................................................................................ 22� NepalFreePacket .............................................................................................. 22� NepalResetAdapter .......................................................................................... 23� NepalGetInfo.................................................................................................... 24� NepalGetStat .................................................................................................... 25� NepalGetFilter.................................................................................................. 26� NepalSetFilter .................................................................................................. 27� NepalGetMCList.............................................................................................. 29� NepalSetMCList .............................................................................................. 30� NepalGetProtocol............................................................................................. 31� NepalSetProtocol ............................................................................................. 33� NepalResetProtocol.......................................................................................... 34� NepalGetMaxSimReads................................................................................... 36� NepalGetLastError........................................................................................... 37

5.5 Selección de adaptadores ...................................................................................... 38� NepalGetAvailAdapterNames ......................................................................... 38� NepalSelectAdapter ......................................................................................... 39

5.6 Conversión y comparación ................................................................................... 40� ETH_COMPARE_NETWORK_ADDRESSES_EQ ...................................... 40� ETH_IS_MULTICAST ................................................................................... 41� INV .................................................................................................................. 42� NepalEther2Byte.............................................................................................. 43� NepalIP2Byte................................................................................................... 44

5.7 Impresión de resultados ........................................................................................ 45


5.8 Tipos y estructuras de datos.................................................................................. 46� ADAPTER ....................................................................................................... 46� ADAPTER_INFO............................................................................................ 46� ETHERNET_FRAME ..................................................................................... 48� ETHERNET_ADDRESS................................................................................. 48� IP_ADDRESS.................................................................................................. 48� PACKET.......................................................................................................... 48� NepalGlobalSupportedOids ............................................................................. 48

5.9 Constantes ............................................................................................................. 526. Desarrollo de protocolos sobre NEPAL................................................................. 53


El entorno de programación del laboratorio se basa en el uso de ordenadores consistema operativo Windows NT sobre los que se accede a tarjetas de red Ethernetmediante interfaces NDIS.

Para simplificar las labores de interacción con el interfaz NDIS, los alumnos accederána la librería denominada NEPAL: NDIS Ethernet Packet Access Library, disponibleen todos los ordenadores del laboratorio. Mediante esta librería se dispone de funcionesespecíficas para el envío y recepción de datos, así como para la programación de losinterfaces.

En los siguientes apartados se muestra una introducción a la librería NEPAL, así comouna especificación detallada de todas las funciones disponibles.

1. Introducción a la librería NEPAL

La Figura 1 muestra los distintos componentes de NEPAL, las relaciones entre sí y conlos principales componentes del entorno.

La arquitectura de NEPAL se ha definido según la propia arquitectura del sistemaoperativo, que, en el caso particular de Windows NT, se caracteriza entre otros por lossiguientes:

- Existencia de dos modos de ejecución: usuario y kernel, como mecanismo deprotección del sistema.

- Diseño en niveles del subsistema de red, utilizando la especificación NDIS parala comunicación de los niveles más bajos entre sí.

- Existencia de un subsistema de Entrada/Salida, I/O Manager, que establece unainterfaz genérica entre las aplicaciones en modo usuario y los drivers en modokernel. Esta interfaz sigue el modelo bien conocido del fichero de Entrada/Salida

La arquitectura que se ha establecido para NEPAL incluye un driver que se ejecuta enmodo kernel, y que realiza el acceso directo y completo al adaptador de red a través dela biblioteca NDIS de interfaz. El otro componente es la biblioteca NEPAL, quemediante una interfaz privada accede al controlador y proporciona a las aplicaciones lainterfaz pública NEPAL.


Figura 1 Arquitectura general del entorno NEPAL.


2. Características de NEPAL

El Gestor de Entrada/Salida de Windows NT junto con la biblioteca NDIS reúnen unconjunto de características muy interesantes que se incorporan en la arquitecturaNEPAL como son las siguientes:

• Múltiples accessos a múltiples tarjetas.• Tramas reflejadas.• Sincronismo en las operaciones de Entrada/Salida• Filtros

En los siguientes apartados se describen estas características.

• Múltiples accesos a múltiples tarjetas

La biblioteca NDIS y el Gestor de E/S se las arreglan para permitir que distintosprocesos accedan simultáneamente a uno o varios adaptadores de red. Incluso, dentro deun mismo proceso, se pueden solicitar al Gestor de E/S varios manejadores a distintosobjetos que hacen referencia a un mismo adaptador físico, comportándose de formaindependiente cada uno de ellos.

Expresado de otro modo, una aplicación puede acceder de forma múltiple y simultáneaal adaptador de red y la arquitectura subyacente se encarga de actuar de tal forma quecada acceso funcione como si fuera único desde el punto de vista de la aplicación.

A modo de ejemplo, en uno de los accesos se puede poner el adaptador en modopromiscuo y recibir todas las tramas de la red, mientras que, simultáneamente, poner enel otro acceso el adaptador en modo dirigido y recibir por el solo tramas dirigidas a ladirección del adaptador. Cada uno de estos “accesos” se denomina binding y se dice quela arquitectura (NDIS) almacena una configuración independiente por cada binding,incluyendo el filtro activo.

• Tramas reflejadas

Se denominan tramas reflejadas a aquellas tramas originadas por un nivel superior aNDIS que son devueltas al nivel superior para consumo de los clientes, sin que seantramas que físicamente procedan de la red.

Mediante esta función una aplicación que se ejecute en una máquina recibira las tramasque otra aplicación del mismo ordenador envíe a la red.

En el caso en el que la dirección destino de la trama a enviar coincida con la direccióndel adaptador, la trama ni siquiera se transmite por la red, no baja al nivel físico, sinoque es reflejada a los niveles superiores, en el caso de que exista algún consumidor de lamisma.


Las tramas reflejadas pueden tener un tamaño mínimo inferior al especificado para elmedio. En Ethernet, si envío una trama de 40 bytes de tamaño total, NDIS va a rellenarcon bytes hasta llegar a 60 para enviarla por la red, pero va a reenviar a los nivelessuperiores la trama intacta de 40 bytes como trama reflejada.

El programador de NEPAL debe tener en cuenta esta propiedad cuando diseñe ciertasaplicaciones, como es el caso de un Bridge.

• Sincronismo en las operaciones de Entrada/Salida

Las operaciones de entrada/salida (Lecturas, escrituras, modificación de parámetros decontrol) pueden realizarse de modo síncrono o bien de modo asíncrono. En modosíncrono, una vez que la función es llamada por la aplicación, ésta queda suspendidahasta que la operación de Entrada/Salida no finalice.

Realizadas en modo asíncrono, la aplicación continúa ejecutándose después de haberllamado a la función y obtiene una estructura de datos que sirve para comprobar conposterioridad si la operación se ha finalizado o continúa pendiente. Este modo deoperación, proporcionado por el avanzado Gestor de E/S de Windows NT proporciona ala aplicación la posibilidad de efectuar otras operaciones mientras tanto.

Es posible utilizar esta característica para mejorar la tasa de captura de tramas de red,reduciendo la probabilidad de perder una trama de red por estar ocupado realizandootras actividades.

Esta técnica consiste en lanzar de una vez, y al inicio, un número grande de lecturasasíncronas que quedarán pendientes de completar a medida que lleguen las tramas de lared y la aplicación las procese. Si la aplicación está ocupada en otros procesamientos, deforma que no pueda atender el ritmo de entrada de tramas por el adaptador, las tramas sevan recibiendo y almacenando en el gestor de E/S en forma de paquetes de E/S hastaque la aplicación pueda procesarlos. Según los procese, la aplicación solicitará nuevaslecturas asíncronas al gestor de E/S. El número máximo de operaciones de E/Spendientes de resolución lo determina el driver y normalmente es un parámetroestablecido en tiempo de compilación.

• Filtros

La biblioteca NDIS se encarga de gestionar los denominados filtros de dirección deladaptador, que definen los criterios según los cuales el adaptador pasa una trama a losniveles superiores, atendiendo a la dirección de destino de la trama.

En la librería se ha introducido la posibilidad de activar un filtro adicional según elprotocolo de la trama que se recibe.

Para la implementación del filtrado por protocolo, tal y como hemos denominado a estacaracterística original, aprovechamos que NDIS llama al driver NEPAL cuando la trama


se empieza a recibir, pasando al driver la cabecera de la trama que se está recibiendo(lookahead pointer). Desde el driver se comprueba si para el binding en particular hayestablecido el filtrado por protocolo y, en caso afirmativo, comprobar si ambosprotocolos coinciden. Si coinciden, entonces se puede completar la recepción de latrama. Si no coinciden, la operación de lectura se aborta y no se gasta mas tiempo enrecibir una trama que no se necesita.

3. Guia de Programación de NEPAL

• Instrucciones generales de uso

El programador deberá incluir el fichero “nepal.h” en los ficheros C/C++ que hagan usode la biblioteca. En este fichero se encuentran todas las declaraciones de funciones,tipos de datos y constantes que componen la biblioteca. Se recomienda que añada eldirectorio donde se encuentra “nepal.h” en la opción del compilador que especifica losdirectorios donde debe buscar ficheros “include”. En dicho directorio (en el laboratorio“c:\nepal\inc\” o bien “d:\nepal\inc\”) se encuentran otros ficheros necesarios para lacompilación. Para poder compilar debe incluirse la variable NEPALDLL_ en el ámbitodel preprocesador.

En las opciones de enlazado (link) del proyecto, deberá indicar que debe enlazar con labiblioteca de importación “nep10.lib”, indicando el directorio donde se encuentra estabiblioteca en la opción de directorio de bibliotecas de la llamada al linker.

El código de la biblioteca NEPAL no se enlaza con el programa en tiempo decompilación, sino de forma dinámica en tiempo de ejecución, por lo que es necesarioque la biblioteca “nep10.dll” se encuentre en el mismo directorio que el ejecutablecuando la aplicación se ejecute (o en algún directorio presente en la variable de entorno“PATH”).

El enlazado con la biblioteca de importación “nep10.lib” no incluye por tanto el códigode NEPAL en el ejecutable, sino las instrucciones necesarias para llamar a dicho códigoen tiempo de ejecución. El código ejecutable de NEPAL se encuentra en la biblioteca deenlace dinámico “nep10.dll”.


• Envío de tramas

El API NEPAL ofrece un conjunto sencillo de funciones y estructuras de datos quepermiten la interacción con la red.

El siguiente fragmento de código muestra la operación de envío de trama.

...LPADAPTER lpAdap;ETHERNET_FRAME trama;

lpAdaptador = NepalOpenAdapter(“0001”);

NepalEther2Byte(TEXT("ff:ff:ff:ff:ff:ff"),trama.DestinationAddress

);

memcpy(trama.SourceAddress,lpAdap->CurrentAddress, ETHERNET_ADDRESS_LENGTH

);

trama.Protocol = INV(0x08AB);

memset(&(trama.Data[0]),0x00,

(ETHERNET_PACKET_LENGTH - ETHERNET_HEADER_LENGTH));

NepalSendPacket(lpAdaptador, &trama, 60);

...

NepalCloseAdapter(lpAdap);...


• Recepción de tramas

Las operaciones de lectura pueden ser asíncronas, para que el programa pueda seguirrealizando otras tareas mientras la de E/S se completa. El siguiente fragmento de códigomuestra laoperación de lectura (recepción) asíncrona:

...

LPPACKET lpPacket;LPADAPTER lpAdap;ETHERNET_FRAME trama;

lpAdaptador = NepalOpenAdapter(“0001”);

NepalSetFilter( lpAdap, NDIS_PACKET_TYPE_PROMISCUOUS);

NepalReadPacket(lpAdap, &lpPacket, FALSE);

while(TRUE){

if (NepalCheckForData(lpAdaptador,&lpPacket,&trama,&ulBytesReceived,FALSE)){

//trama recibida

//imprimir en pantallaNepalWriteEtherFrame(&trama, ulBytesReceived, FALSE);

//leer otraNepalReadPacket(lpAdaptador, &lpPacket, FALSE);

} else{ ... }}

NepalFreePacket(lpPacket);

...

NepalCloseAdapter(lpAdap);...


4. Referencia del API NEPAL

En este apartado se describe en detalle las distintas funciones y estructuras de datosproporcionadas por el API NEPAL. La definición detallada de cada una de lasestructuras de datos y funciones, parámetros de entrada y salida, etc, puede consultarseen la siguiente sección.

El entorno de desarrollo NEPAL proporciona a las aplicaciones Win32 un mecanismopara acceder a los controladores NDIS de adaptadores de red, a través de una interfaz deprogramación de aplicaciones (API) exportada por la biblioteca de enlace dinámico“nep10.dll”.

La biblioteca NEPAL proporciona en realidad dos interfaces de programación, una demayor nivel de abstracción (nivel 2) y otra de menor (nivel 1). En esta sección seexplica con detalle la interfaz de mayor nivel de abstracción ya que es más fácil deutilizar y cubre todas las necesidades de programación de adaptadores de red. Estainterfaz será la que se utilice en el desarrollo de las prácticas.

Las funciones de la interfaz de nivel 2, cuyos nombres comienzan con “Nepal”, estánimplementadas utilizando las funciones de nivel 1. En lo sucesivo hablaremos defunciones de interfaz de NEPAL refiriéndonos a las funciones que se utilizarán en ellaboratorio (Funciones de nivel 2).

• Descripción general del interfaz de NEPAL

Las funciones de la interfaz de programación se agrupan en los apartados descritos acontinuación.

q Funciones principales.

Apertura/cierre del adaptador.

• NepalOpenAdapter, abre un adaptador NDIS y devuelve un manejadorutilizado en las siguientes llamadas a funciones referidas a dicho adaptador.

• NepalCloseAdapter, cierra un adaptador.

Envío de tramas.

• NepalSendPacket, envía una trama.

Recepción de tramas.

• NepalReadPacket, inicia una operación de lectura de una trama.• NepalCheckForData, comprueba la recepción de una trama en una operación

de lectura iniciada previamente.


Control y solicitud de información al controlador y al adaptador.

• NepalFreePacket, elimina un paquete de comunicación con el controlador.• NepalResetAdapter, reinicia el adaptador.• NepalGetInfo, obtiene toda la información disponible del adaptador.• NepalGetStat, obtiene información estadística del adaptador.• NepalGetFilter, obtiene el filtro configurado en el adaptador.• NepalSetFilter, configura un filtro en el adaptador.• NepalGetMCList, obtiene la lista de direcciones multicast del adaptador.• NepalSetMCList, configura la lista de direcciones multicast del adaptador.• NepalGetProtocol, obtiene el filtro de protocolo del controlador.• NepalSetProtocol, configura el filtro de protocolo del controlador.• NepalResetProtocol, deshabilita filtrado por protocolo en el controlador.• NepalGetMaxSimReads, obtiene el número máximo de lecturas pendientes que

soporta el controlador.• NepalGetLastError, obtiene el código del último error producido.

q Funciones de soporte.

Selección de adaptadores

• NepalGetAvailAdapterNames, obtiene los nombres de adaptadores disponiblesen el sistema.

• NepalSelectAdapter, en modo consola, permite al usuario seleccionar unadaptador de los disponibles.

Conversión y comparación de datos.

• ETH_COMPARE_NETWORK_ADDRESSES_EQ, compara dosdirecciones.

• ETH_IS_MULTICAST, comprueba si una dirección es multicast.• INV, cambia el orden de los bytes en una palabra• NepalEther2Byte, convierte a bytes una dirección Ethernet en formato

“XX:XX:XX:XX:XX:XX”.• NepalIP2Byte, convierte a bytes una dirección IP en formato “X.Y.Z.T”.


Impresión de resultados.

Estas funciones imprimen en modo consola distintos tipos de información en suformato más adecuado.

• NepalWriteEtherAddress• NepalWriteEtherFrame• NepalWriteFilter• NepalWriteInfo• NepalWriteIPAddress• NepalWriteOidList• NepalWriteMediaList• NepalWriteState• NepalWriteGenMacOptions• NepalWriteMacOptions• PAUSA

• Tipos y estructuras de datos

En la interfaz NEPAL se exportan y utilizan las siguientes estructuras de datos.

• ADAPTER, almacena información para identificar un adaptador abierto.• ADAPTER_INFO, almacena la información completa sobre el adaptador.• ETHERNET_FRAME, almacena la información de una trama Ethernet.• ETHERNET_ADDRESS, almacena una dirección Ethernet.• IP_ADDRESS, almacena una dirección IP.• PACKET, almacena información para que una aplicación en modo usuario se

comunique con un controlador en modo kernel.• NepalGlobalSuportedOids, listado de los OID soportados por un controlador

de un adaptador Ethernet NDIS.

• Constantes

En la interfaz NEPAL se definen las siguientes constantes.

• ETHERNET_ADDRESS_LENGTH• ETHERNET_PACKET_LENGTH• ETHERNET_HEADER_LENGHT• IP_ADDRESS_LENGTH• MAX_MC_LIST• MAX_LINK_NAME_LENGTH• MAX_ADAPTERS• NEPAL_SUPPORTED_OIDS


5. Descripción detallada del Interfaz de NEPAL

5.1 Apertura / Cierre del adaptador

• NepalOpenAdapter

La función NepalOpenAdapter sirve para abrir un controlador NDIS de adaptadorespecífico.

PVOID __stdcall NepalOpenAdapter( LPTSTR AdapterName );

Parámetros

AdapterNameEl nombre del controlador NDIS de adaptador que se desea abrir.

Valor de retorno

Si la función se completa con éxito, devuelve la dirección a una estructura de tipoADAPTER que identifica al controlador NDIS de adaptador abierto.

Si la función falla devuelve el valor NULL. En este caso, puede llamar a la funciónNepalGetLastError para obtener mas información sobre la causa del error.

Observaciones

El puntero a la estructura de tipo ADAPTER devuelta por la función debe utilizarsecada vez que se llama a otras funciones de la biblioteca NEPAL que acceden alcontrolador en cuestión. La función inicializa la información sobre el adaptador en loscampos de la estructura ADAPTER.

Debe utilizarse la función NepalCloseAdapter para cerrar el controlador NDIS deadaptador devuelto por NepalOpenAdapter.

Puede utilizar la función NepalGetAvailAdapterNames para conocer los adaptadores dered disponibles en el sistema.


Portabilidad

Windows NT

El nombre del controlador, AdapterName, es el nombre del dispositivo DosDevice de latarjeta de red o adaptador. Un nombre de este tipo podría ser:

“\Device\Nepal_NE20001”

Windows 9X

El nombre del controlador, AdapterName, es el valor de la clave del adaptador que seencuentra en:

“HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\Net”

Un nombre de este tipo podría ser:

“0001”

En cualquiera de los casos, se puede utilizar la función NepalGetAvailAdapterNamespara obtener los nombres de adaptadores disponibles en el sistema.

Véase también

NepalCloseAdapter, ADAPTER, NepalGetAvailAdapterNames

• NepalCloseAdapter

La función NepalCloseAdapter sirve para cerrar un controlador NDIS previamenteabierto con la función NepalOpenAdapter.

VOID __stdcall NepalCloseAdapter( LPADAPTER lpAdapter );

Parámetros

lpAdapterEl nombre del controlador NDIS de adaptador que se desea cerrar. Debe ser ladirección de una estructura de tipo ADAPTER devuelta por una llamada a lafunción NepalOpenAdapter


Valor de retorno

Ninguno.

Observaciones

Después de la llamada a la función NepalCloseAdapter, la estructura de tipo ADAPTERque se pasa como parámetro se elimina de memoria y no se puede utilizar más.

Portabilidad

Windows 9XSi existen varios programas que tienen abierto simultáneamente un adaptador, ya sea elmismo o distintos, el primer programa que cierra el adaptador provoca que se cierren losadaptadores en el resto de programas.

Windows NTFunciona correctamente sin la limitación existente en Windows 9X.

Véase también

NepalOpenAdapter

5.2 Envío de tramas

• NepalSendPacket

La función NepalSendPacket se utiliza para enviar una trama a la red a través de unadaptador NDIS específico.

BOOLEAN __stdcall NepalSendPacket(LPADAPTER lpAdapter,LPETHERNET_FRAMElpEthFrame,UINT uiEthFrameTotalSize);

Parámetros

lpAdapterIndica el adaptador NDIS utilizado para la operación. La dirección debe apuntara una estructura ADAPTER válida, devuelta mediante una llamada previa a lafunción NepalOpenAdapter.


lpEthFrameUn puntero a una estructura de tipo ETHERNET_FRAME que contiene losdatos de la trama a enviar.

uiEthFrameTotalSizeIndica la longitud total de la trama a enviar. La longitud es la de toda la tramacompleta, incluyendo la cabecera Ethernet.

Valor de retorno

Si la función se completa con éxito, devuelve el valor TRUE. En caso contrariodevuelve FALSE. En este caso, puede llamar a la función NepalGetLastError paraobtener mas información sobre la causa del error.

Observaciones

La trama pasada como parámetro lpEthFrame, debe contener toda la trama a enviar,incluyendo la cabecera Ethernet. No incluye los bytes finales de checksum.

Algunos adaptadores de red reescriben la dirección origen en la trama que transmiten,escribiendo en su lugar la dirección activa del propio adaptador; por consiguiente no sepuede confiar en que la dirección origen que efectivamente se transmita al mediocontenga la dirección origen que se ha pasado en la trama a la función.

La función copia los datos de la trama que se le pasa como parámetro a un área dealmacenamiento interno, hasta un total de uiEthFrameTotalSize bytes. La tramaque se le pasa como parámetro es por tanto independiente de la operación de envío unavez finalizada la llamada a la función.

El envío mediante la función NepalSendPacket es de tipo síncrono. Esto significa que lafunción no retorna hasta que no finaliza la operación de envío de la trama o se haproducido un error.

Si existe una lectura pendiente (llamando a NepalReadPacket) o, en ocasiones, cuandose realiza inmediatamente a continuación, además de enviar la trama por la red, tambiénla recibe el propio controlador NDIS del adaptador (lo que se conoce como tramasreflejadas). Consulte la función NepalCheckForData para mayor información sobre lastramas reflejadas.

Portabilidad

Soportado en Windows NT y Windows 9X.

Véase también

NepalOpenAdapter, ADAPTER, ETHERNET_FRAME, NepalReadPacket,NepalCheckForData


5.3 Recepción de tramas

• NepalReadPacket

La función NepalReadPacket se utiliza para iniciar una operación de recepción de unatrama de la red a través de un adaptador NDIS específico.

BOOLEAN __stdcall NepalReadPacket(LPADAPTER lpAdapter,LPPACKET *lplpPacket,BOOLEAN bSync);

Parámetros


lplpPacketLa dirección de un puntero a una estructura de tipo PACKET usada para recibirla trama.

bSyncIndica si la recepción debe ser síncrona o asíncrona. El valor TRUE significaque NepalReadPacket no retorna hasta que la operación de Entrada/Salida no secompleta. Se recomienda no utilizar este modo de recepción síncrono.

El valor FALSE en el parámetro bSync significa que la recepción es asíncrona,y la función NepalReadPacket retorna inmediatamente. Para obtener el resultadode la operación de lectura se debe examinar la estructura apuntada porlplpPacket utilizando la función NepalCheckForData.

Valor de retorno

La función NepalReadPacket devuelve TRUE si ha podido iniciar sin problemas laoperación de recepción de trama.

Si se ha producido un error, la función devuelve FALSE. En este caso, puede llamar a lafunción NepalGetLastError para obtener mas información sobre la causa del error.


Observaciones

Después de iniciar una operación asíncrona de recepción de trama, el modorecomendado, se debe examinar la estructura apuntada por el puntero en la direcciónlplpPacket utilizando la función NepalCheckForData. La función NepalCheckForDatadetermina si la operación iniciada se ha completado o no.

Cuando queda completada con éxito la operación pendiente de lectura significa que seha recibido una trama. Consulte la función NepalCheckForData para conocer comoacceder a la trama recibida.

El número máximo de lecturas asíncronas pendientes que puede soportar el controladorpuede consultarse con la función NepalGetMaxSimReads.

El modo de recepción asíncrono permite ademas la ejecución de otro código mientras seestá esperando la recepción de tramas. Mediante el inicio de múltiples solicitudes delectura asíncrona de forma simultánea, la tasa de pérdidas de tramas se puede reducirhasta niveles aceptables en aplicaciones estándares.

Es importante indicar que no todos las tramas que recibe un adaptador de red seentregan a las aplicaciones que usan dicho adaptador. El controlador NDIS deladaptador utiliza dos tipos de filtros: por dirección de destino de la trama y porprotocolo. Además, se mantiene un filtro de cada tipo (dirección y protocolo) por cadabinding, de forma que los filtros establecidos por una aplicación que utiliza elcontrolador NDIS no afectan a los establecidos por otra. Inicialmente, el controladorNDIS del adaptador tiene la siguiente configuración de filtros:

- Por dirección: ninguno, no recibe ninguna trama. Active un filtro dedirección con la función NepalSetFilter para recibir tramas de algún tipo.

- Por protocolo: ninguno, recibe tramas de cualquier protocolo. Active unfiltro de protocolo con la función NepalSetProtocol para recibir solo tramasde un protocolo en particular.

Portabilidad


1.1.1.1 Véase también

NepalOpenAdapter, ETHERNET_FRAME, PACKET, NepalCheckForData,NepalGetMaxSimReads, NepalSetFilter, NepalSetProtocol


• NepalCheckForData

La función NepalCheckForData se utiliza para determinar si se ha completado unaoperación de recepción asíncrona de trama iniciada previamente mediante una llamada aNepalReadPacket. En caso de que se complete mediante la recepción de la trama,permite obtener la información de la trama recibida.

BOOLEAN __stdcall NepalCheckForData(LPADAPTER lpAdapter,LPPACKET *lplpPacket,LPETHERNET_FRAMElpEthFrame,PULONG lpulBytesReceived,BOOLEAN bSync);

Parámetros


lplpPacketLa dirección de un puntero a una estructura de tipo PACKET inicializada en unallamada previa a NepalReadPacket de operación de lectura asíncrona.

lpEthFrameDirección a una estructura de tipo ETHERNET_FRAME donde se copiarán losdatos de la trama, en el caso de que la operación de lectura se complete conéxito, es decir, se reciba la trama.

lpulBytesReceivedLongitud en bytes de la trama recibida y copiada en lpEthFrame , solo en elcaso de que la operación de lectura se complete con éxito, es decir, se reciba latrama.

bSyncIndica si la comprobación debe ser síncrona o asíncrona. El valor TRUEsignifica que NepalCheckForData no retorna hasta que la operación deEntrada/Salida no se completa. A diferencia de NepalReadPacket, la llamada a lafunción NepalCheckForData puede realizarse en modo síncrono o asíncronodependiendo de la lógica de la aplicación.

El valor FALSE en el parámetro bSync significa que la recepción es asíncrona,y la función NepalCheckForData retorna inmediatamente. Para obtener elresultado de la operación de lectura se debe examinar la estructura apuntada porlplpPacket utilizando de nuevo la función NepalCheckForData.


Valor de retorno

La función NepalCheckForData devuelve el valor TRUE si ha completado la operaciónde lectura asíncrona a la que hace referencia lplpPacket, es decir, si ha recibido la trama.

Devuelve el valor FALSE si la operación de lectura no se ha completado.

Observaciones

La trama recibida se copia en la estructura de tipo ETHERNET_FRAME cuya direcciónse pasa como parámetro (lpEthFrame) y contiene toda la trama recibida por eladaptador NDIS, incluyendo la cabecera Ethernet. No incluye los bytes finales dechecksum.

Cuando la trama se recibe, la aplicación es libre de utilizar la estructura de tipoETHERNET_FRAME cuya dirección es lpEthFrame como desee, sin que esto afecteal funcionamiento de la biblioteca o del controlador NDIS del adaptador. En otraspalabras, ni el controlador ni la biblioteca acceden a esta estructura de datos una vez quela función copia la trama en ella y retorna de la función NepalCheckForData.

Cuando otro componente NDIS del sistema, por ejemplo el controlador de protocoloTCP/IP, envía una trama al adaptador, la aplicación que está esperando una tramamediante el controlador NEPAL, recibe la trama a través de la biblioteca NDIS, no através del adaptador de red. Estas tramas se denominan tramas reflejadas o de bucleNDIS. Si la longitud en bytes de la trama original no es superior al mínimo exigido porel medio (60 bytes en Ethernet, sin contar el campo CRC), la biblioteca NDIS pasa latrama al adaptador rellenada con el resto de bytes, sin embargo no suele rellenar conbytes cuando la pasa a los controladores de protocolo, en este caso NEPAL, que tenganlecturas NDIS pendientes. En cualquier caso, al enviar tramas de tamaño menor almínimo no hay que preocuparse de completar ya que la biblioteca NDIS lo hace pornosotros.

En otras palabras, una trama reflejada recibida mediante la función NepalCheckForDatapuede tener una longitud menor que la longitud mínima que establece el medio.

Portabilidad


Véase también

NepalOpenAdapter, ADAPTER, ETHERNET_FRAME, NepalReadPacket


5.4 Control y solicitud

• NepalFreePacket

La función NepalFreePacket elimina los recursos reservados mediante la llamada a lafunción NepalReadPacket y que están asociados a una operación de lectura asíncronapendiente.

VOID __stdcall NepalFreePacket(LPPACKET lpPacket);

Parámetros

lpPacketDirección de la estructura de datos de tipo PACKET devuelta en la llamada a lafunción NepalReadPacket, que identifica una operación de lectura asíncronapendiente.

Valor de retorno

Ninguno.

Observaciones

Si lpPacket no hace referencia a ningún recurso reservado (es NULL), la función nohace nada.

La función NepalFreePacket se utiliza cuando queremos eliminar los recursos, espacioen memoria para recibir la trama y bloqueos (locks) asociados a dicho espacio, quehacen referencia a una petición de lectura asíncrona que está pendiente de completarse.Normalmente estos recursos se liberan cuando se recibe la trama con la llamada aNepalCheckForData. Sin embargo existen ocasiones en las que se quiere desechar laslecturas pendientes, por ejemplo para realizar nuevas lecturas o al salir del programa.

Muy importante: la función NepalFreePacket debe ejecutarse por cada una de laslecturas pendientes no completadas antes de llamar a la función NepalCloseAdapter. Sepasará como argumento a la función la dirección de cada estructura PACKET reservadamediante NepalReadPacket que se refiera a una operación no completada.

PortabilidadSoportado en Windows NT y Windows 9X.


Véase tambiénNepalReadPacket, PACKET, NepalCheckForData, NepalCloseAdapter

• NepalResetAdapter

La función NepalResetAdapter efectúa una solicitud de reinicialización al adaptador dered asociado al manejador que se le pasa como parámetro y que ha sido previamenteabierto.

VOID __stdcall NepalResetAdapter( LPADAPTER lpAdapter );

Parámetros


Valor de retorno

Ninguno.

Observaciones

La biblioteca NDIS realiza una llamada a la función de reinicialización del controladordel adaptador de red (NDIS NIC driver). El controlador del adaptador de red deberíareinicializar su estado interno, si bien esto depende de la implementación específica decada controlador del adaptador de red.

Portabilidad


Véase también

NepalOpenAdapter, ADAPTER


• NepalGetInfo

La función NepalGetInfo solicita información al controlador sobre el adaptador de red,devolviendo una estructura de datos con el máximo de información disponible sobre elcontrolador del adaptador de red.

BOOLEAN __stdcall NepalGetInfo(LPADAPTER lpAdapter,PADAPTER_INFO AdapterInfo);

Parámetros


AdapterInfoPuntero a una estructura de tipo ADAPTER_INFO en la que la funciónalmacenará el máximo de información sobre el controlador del adaptador de red.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido obtener la informaciónsolicitada al controlador del adaptador de red. En caso contrario devuelve FALSE. Eneste caso, puede llamar a la función NepalGetLastError para obtener mas informaciónsobre la causa del error.

Observaciones

En la estructura de datos ADAPTER_INFO se almacena la información general delcontrolador del adaptador de red y la información específica del controlador NEPAL.

En las aplicaciones en modo consola, se puede utilizar la función NepalWriteInfo paraimprimir en una ventana MS-DOS la información almacenada en la estructuraADAPTER_INFO.

Otras funciones de obtención de información recuperan individualmente alguno de losdatos que se recuperan en esta llamada.

Portabilidad



Véase también

ADAPTER_INFO, NepalWriteInfo

• NepalGetStat

La función NepalGetStat permite consultar de forma individual información deladaptador de red.

ULONG __stdcall NepalGetStat(LPADAPTER lpAdapter,ULONG ulOid);

Parámetros


ulOidUna de las constantes definidas que hacen referencia a la información que sequiere solicitar al adaptador. Puede consultar la lista de OIDs (Object Identifier)disponibles y su significado en el tipo de datos definidoNepalGlobalSupportedOids.

Valor de retorno

Devuelve el valor del OID solicitado que almacena en el momento de la llamada elcontrolador del adaptador de red o el controlador NEPAL.

Observaciones

No todos los OIDs se pueden pasar como parámetros, sino solamente aquellos que sepueden consultar y que el tipo es ULONG.

Portabilidad



Véase también

NepalGlobalSupportedOids, NepalGetInfo, ADAPTER_INFO

• NepalGetFilter

La función NepalGetFilter permite obtener el filtro de dirección actualmenteconfigurado en el controlador del adaptador de red especificado.

Un filtro de dirección es un valor que indica las tramas recibidas por el adaptador de redque éste pasará al controlador NEPAL, en función la dirección de destino de la tramarecibida por el adaptador.

BOOLEAN __stdcall NepalGetFilter(LPADAPTER lpAdapter,PULONG lpFilter);

Parámetros


lpFilterPuntero a una variable de tipo ULONG donde al retornar de la función sealmacena el valor del filtro de dirección actualmente configurado en eladaptador.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido obtener la información sobre elfiltro de dirección solicitada al controlador del adaptador de red. En caso contrariodevuelve FALSE. En este caso, puede llamar a la función NepalGetLastError paraobtener mas información sobre la causa del error.

Observaciones

El filtro de dirección es inicialmente cero, lo que significa que no recibe ninguna trama.

Los filtros de dirección se establecen por binding, es decir para cada adaptador y paracada aplicación.


Consulte la función NepalSetFilter para conocer los distintos filtros y suscorrespondientes significados.

En una aplicación en modo consola, se puede utilizar la función NepalWriteFilter paraimprimir por pantalla las constantes que representan el valor del filtro obtenido.

Portabilidad

Windows 9XLos filtros de dirección no se almacenan por binding, lo que significa que si dos o másaplicaciones tienen abierto un adaptador y una de ellas cambia el filtro, el filtro activopara todas las aplicaciones es el último que se ha establecido.

Windows NTLos filtros sí se almacenan por binding.

Véase también

NepalSetFilter, NepalGetInfo, ADAPTER_INFO, NepalWriteFilter

• NepalSetFilter

La función NepalSetFilter permite establecer un filtro de dirección en el controlador deladaptador de red especificado.

Un filtro de dirección es un valor que indica las tramas recibidas por el adaptador de redque éste pasará al controlador NEPAL, en función la dirección de destino de la tramarecibida por el adaptador.

BOOLEAN __stdcall NepalSetFilter(LPADAPTER lpAdapter,ULONG Filter);

Parámetros


FilterEl valor resultante de realizar una operación binaria OR de alguna de lasconstantes definidas.


Valor de retorno

La función devuelve el valor lógico TRUE si ha podido configurar el filtro de direcciónen el controlador del adaptador de red. En caso contrario devuelve FALSE. En estecaso, puede llamar a la función NepalGetLastError para obtener mas información sobrela causa del error.

Observaciones

Las constantes que se pueden utilizar son las que aparecen en la siguiente tabla junto asu significado correspondiente.

El filtro de dirección es inicialmente cero, lo que significa que no recibe ninguna trama.Debe establecer algún filtro para comenzar a recibir tramas.

Constante SignificadoNDIS_PACKET_TYPE_ALL_FUNCTIONAL Específico para adaptadores Token Ring.NDIS_PACKET_TYPE_ALL_LOCAL Todas las tramas enviadas por protocolos

instalados en el sistema.NDIS_PACKET_TYPE_ALL_MULTICAST Cualquier trama con dirección multicast, no sólo

coincidente con alguna de la lista de direccionesmulticast.

NDIS_PACKET_TYPE_BROADCAST Tramas broadcast.NDIS_PACKET_TYPE_DIRECTED Tramas dirigidas. Las tramas dirigidas contienen

una dirección destino igual a la del adaptador dered.

NDIS_PACKET_TYPE_FUNCTIONAL Específico para adaptadores Token Ring.NDIS_PACKET_TYPE_GROUP No aplicable a adaptadores Ethernet.NDIS_PACKET_TYPE_MAC_FRAME Específico para adaptadores Token Ring.NDIS_PACKET_TYPE_MULTICAST Tramas con direcciones multicast que coinciden con

alguna dirección de la lista de direcciones multicast.NDIS_PACKET_TYPE_PROMISCUOUS Todas las tramas (modo promiscuo).NDIS_PACKET_TYPE_SMT Específico para adaptadores FDDI.NDIS_PACKET_TYPE_SOURCE_ROUTING No aplicable a adaptadores Ethernet.

Tabla 1 Constantes definidas para filtros de dirección.

Los filtros de dirección se establecen por binding, es decir para cada adaptador y paracada aplicación.

Portabilidad

Windows 9XLos filtros de dirección no se almacenan por binding, lo que significa que si dos o másaplicaciones tienen abierto un adaptador y una de ellas cambia el filtro, el filtro activopara todas las aplicaciones es el último que se ha establecido.

Windows NTLos filtros sí se almacenan por binding.


Véase también

NepalGetFilter, NepalGetInfo, ADAPTER_INFO, NepalWriteFilter

• NepalGetMCList

La función NepalGetMCList permite obtener la lista de direcciones multicastalmacenadas en un adaptador de red.

BOOLEAN __stdcall NepalGetMCList(LPADAPTER lpAdapter,ETHERNET_ADDRESS* lpDirEth,PUINT lpLength);

Parámetros


lpDirEthPuntero a una tabla de direcciones Ethernet donde quedarán almacenadas, en elretorno de la función, las direcciones multicast presentes en la lista dedirecciones multicast del adaptador de red.

lpLengthPuntero a una variable entera sin signo donde se almacena el número dedirecciones devueltas.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido obtener la lista de direccionesmulticast almacenadas en el adaptador de red. En caso contrario devuelve FALSE. Eneste caso, puede llamar a la función NepalGetLastError para obtener mas informaciónsobre la causa del error.

Observaciones

Si bien la función se suele ejecutar sin error, se ha comprobado experimentalmente quelos adaptadores de red NDIS no suelen dar soporte al almacenamiento interno dedirecciones multicast. Se recomienda que la propia aplicación establezca un filtro dedirección de tipo NDIS_PACKET_TYPE_ALL_MULTICAST y gestione de forma


particular una lista de direcciones multicast, que puede ser, por otra parte, mas grandeque la propia del adaptador.

Consulte el OID OID_802_3_MAXIMUM_LIST_SIZE para obtener el tamaño de lalista de direcciones multicast del adaptador de red.

Portabilidad


Véase también

NepalSetMCList, NepalGetInfo

• NepalSetMCList

La función NepalSetMCList permite establecer la lista de direcciones multicastalmacenadas en un adaptador de red.

BOOLEAN __stdcallNepalSetMCList(

LPADAPTER lpAdapter,ETHERNET_ADDRESS* lpDirEth,UINT Length);

Parámetros


lpDirEthPuntero a una tabla de direcciones Ethernet donde se encuentran Lengthdirecciones multicast para almacenar en la lista de direcciones multicast deladaptador de red.

LengthVariable entera sin signo cuyo valor indica el número de direcciones multicastque se quiere almacenar en la lista de direcciones multicast del adaptador de red.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido configurar la lista dedirecciones multicast del adaptador de red. En caso contrario devuelve FALSE. En este


caso, puede llamar a la función NepalGetLastError para obtener mas información sobrela causa del error.

Observaciones

Si bien la función se suele ejecutar sin error, se ha comprobado experimentalmente quelos adaptadores de red NDIS no suelen dar soporte al almacenamiento interno dedirecciones multicast. Se recomienda que la propia aplicación establezca un filtro dedirección de tipo NDIS_PACKET_TYPE_ALL_MULTICAST y gestione de formaparticular una lista de direcciones multicast, que puede ser, por otra parte, más grandeque la propia del adaptador.

Consulte el OID OID_802_3_MAXIMUM_LIST_SIZE, en el apartadoNepalGlobalSupportedOids, para obtener el tamaño de la lista de direcciones multicastdel adaptador de red.

Portabilidad


Véase también

NepalGetMCList, NepalGetInfo, NepalGlobalSupportedOids

• NepalGetProtocol

La función NepalGetProtocol permite consultar si el controlador NEPAL especificadotiene activado un filtro de protocolo y, en caso afirmativo, conocer su valor.

Un filtro de protocolo es un valor de dos bytes que establece las tramas recibidas por eladaptador de red que éste pasará al controlador NEPAL, en función del campoprotocolo de la trama recibida por el adaptador.

Esta es una característica original introducida en el controlador NEPAL y no estápresente en la biblioteca NDIS. Se ha introducido por compatibilidad con el packetdriver de MS-DOS.

BOOLEAN __stdcall NepalGetProtocol(LPADAPTER lpAdapter,WORD* lpwProtocol,BOOLEAN* lpbProtocol);


Parámetros


lpwProtocolPuntero a una variable de tipo WORD (dos bytes). Si el controlador NEPALtiene activo un filtro de protocolo (ver parámetro lpbProtocol), al retorno de lafunción la variable contiene el filtro de protocolo activo.

lpbProtocolPuntero a una variable de tipo lógico. Al retorno de la función, la variable tieneel valor lógico TRUE si tiene activado un filtro de protocolo, el controladorNEPAL recibe sólo tramas del protocolo almacenado en la variable que apuntalpwProtocol. La variable tiene el valor lógico FALSE si no tiene activado elfiltro de protocolo, es decir, que recibe tramas de cualquier protocolo.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido consultar si tiene activado elfiltro de protocolo y, en caso afirmativo, su valor. En caso contrario devuelve FALSE.En este caso, puede llamar a la función NepalGetLastError para obtener masinformación sobre la causa del error.

Observaciones

Los filtros de protocolo se establecen por binding, es decir para cada adaptador y paracada aplicación.

Una vez establecido un filtro de protocolo, la aplicación sólo recibe del controladorNEPAL tramas cuyo protocolo coincida con el filtro.

Portabilidad

Soportado sólo por el controlador NEPAL para Windows NT.

Véase también

NepalSetProtocol, NepalResetProtocol, NepalGetInfo


• NepalSetProtocol

La función NepalSetProtocol permite activar un filtro de protocolo configurado en elcontrolador NEPAL especificado.



BOOLEAN __stdcall NepalSetProtocol(LPADAPTER lpAdapter,WORD wProtocol);

Parámetros


wProtocolVariable de tipo WORD (dos bytes) que contiene el filtro de protocolo que sequiere activar en el controlador NEPAL.

Valor de retorno

La función devuelve el valor lógico TRUE si ha podido activar el filtro de protocolo enel controlador NEPAL y configurar su valor. En caso contrario devuelve FALSE. Eneste caso, puede llamar a la función NepalGetLastError para obtener mas informaciónsobre la causa del error.

Observaciones


Una vez establecido un filtro de protocolo, la aplicación sólo recibe del controladorNEPAL tramas cuyo protocolo coincida con el filtro indicado. Si previamente tuvieraun filtro activo, su valor se pierde al ser sustituido por el nuevo filtro.


Para desactivar el filtro de protocolo utilice la función NepalResetProtocol. Paraconsultar el valor actual del filtro de protocolo utilice la función NepalGetProtocol.

El valor del filtro coincide con el valor del campo de protocolo en la trama Ethernet, yno es necesario realizar ninguna reordenación de bytes. Es decir, el byte mássignificativo del valor almacenado en wProtocol corresponde al byte de la posición12 en la trama Ethernet y el menos significativo al byte de la posición 13.

Ejemplo: Si queremos recibir tramas de la forma

ff ff ff ff ff ff 00 11 22 33 44 55 08 06 ...

se debe realizar una llamada a la función NepalSetProtocol con los siguientesargumentos:

NepalSetProtocol(lpAdaptador, 0x0806);

El filtro de protocolo puede ser utilizado en un controlador NEPAL de forma simultáneay complementaria con el filtro de dirección.

Portabilidad


Véase también

NepalGetProtocol, NepalResetProtocol, NepalGetInfo

• NepalResetProtocol

La función NepalResetProtocol permite desactivar el filtro de protocolo configuradopreviamente en el controlador NEPAL especificado.



BOOLEAN __stdcall NepalResetProtocol(LPADAPTER lpAdapter);


Parámetros


Valor de retorno

La función devuelve el valor lógico TRUE si ha podido desactivar el filtro de protocoloen el controlador NEPAL. En caso contrario devuelve FALSE. En este caso, puedellamar a la función NepalGetLastError para obtener mas información sobre la causa delerror.

Observaciones


Una vez desactivado un filtro de protocolo, la aplicación recibe tramas de cualquierprotocolo, siempre que pasen el filtro de dirección. Si previamente tuviera un filtroactivo, su valor se pierde al ser desactivado.

Para activar el filtro de protocolo utilice la función NepalSetProtocol. Para consultar elvalor actual del filtro de protocolo utilice la función NepalGetProtocol.

Portabilidad


Véase también

NepalGetProtocol, NepalSetProtocol, NepalGetInfo


• NepalGetMaxSimReads

La función NepalGetMaxSimReads permite conocer el número máximo de operacionesasíncronas pendientes que soporta el controlador NEPAL que se está utilizando.

int __stdcall NepalGetMaxSimReads(LPADAPTER lpAdapter);

Parámetros


Valor de retorno

La función devuelve el valor lógico TRUE si ha podido consultar el valor solicitado. Encaso contrario devuelve FALSE. En este caso, puede llamar a la funciónNepalGetLastError para obtener mas información sobre la causa del error.

Valor de retorno

La función devuelve el número máximo de operaciones de entrada/salida pendientesque puede gestionar el controlador.

Observaciones

El número máximo de operaciones de entrada/salida pendientes que puede gestionar elcontrolador es un valor establecido en la compilación del controlador y por lo tanto noes variable en tiempo de ejecución. Determina el número de operaciones de lectura detramas de red que una aplicación puede solicitar a la vez al controlador. Cuanto mayorsea este número, menor será la probabilidad de que el controlador pierda tramas de lared recibidas por el adaptador.

Se distribuyen controladores con capacidad para 4 y 64 lecturas pendientes. Si elprogramador necesita otros valores, deberá modificar este parámetro y recompilar elcontrolador NEPAL.

Portabilidad


Véase también

NepalGetInfo


• NepalGetLastError

En caso de que se produzca un fallo en la llamada a alguna función de la bibliotecaNEPAL, se puede utilizar la función NepalGetLastError para obtener informaciónadicional sobre la causa del fallo.

DWORD __stdcall NepalGetLastError();

Parámetros

Ninguno.

Valor de retorno

Devuelve la causa del último fallo producido, codificada como un valor de tipoDWORD.

Observaciones

Después de llamar a esta función, la variable persistente de error se actualiza al valorERROR_SUCCESS.

Para obtener un texto de error a partir de los códigos de error del sistema puede utilizarla función Win32 FormatMessage. Un listado completo de los códigos de error seencuentra en el documento “Error_Codes” de la documentación del SDK y en el fichero“WINERROR.H”, también del SDK.

Portabilidad


Véase también

NepalGetInfo


5.5 Selección de adaptadores

• NepalGetAvailAdapterNames

La función NepalGetAvailAdapterNames sirve para consultar en el sistema y obtenerinformación sobre los adaptadores instalados en el mismo.

int __stdcall NepalGetAvailAdapterNames(_TCHAR* names,_TCHAR *desc,int iDesc);

Parámetros

namesPuntero a una zona de memoria para que la función almacene los nombres de losadaptadores de red disponibles en el sistema. Los nombres se devuelvenseparados por el carácter nulo genérico, TEXT(‘\0’), y termina con dos nulosseguidos.

descPuntero a una zona de memoria para que la función almacene una descripción delos adaptadores de red disponibles en el sistema. Las descripciones se devuelvenen el mismo orden que los nombres, separados por un carácter nulo genérico,TEXT(‘\0’), y termina con dos nulos seguidos.

iDescValor entero de entrada que indica el número máximo de bytes reservados en elparámetro desc para almacenar descripciones.

Valor de retorno

Devuelve el número de adaptadores de red encontrados en el sistema. Devuelve 0 si nohay ninguno y -1 si se ha producido algún error.

Observaciones

Los nombres que la función NepalGetAvailAdapterNames almacena en la variablenames pueden ser utilizados posteriormente con la función NepalOpenAdapter paraabrir el adaptador correspondiente.

En aplicaciones en modo consola se puede utilizar la función NepalSelectAdapter parapermitirle al usuario la selección de un adaptador a través de un menú en pantalla.


Portabilidad


Véase también

NepalSelectAdapter, NepalOpenAdapter

• NepalSelectAdapter

La función NepalSelectAdapter permite, en aplicaciones en modo consola, mostrar unmenú con los distintos adaptadores existentes en un sistema y solicitar al usuario queseleccione uno de ellos.

int __stdcall NepalSelectAdapter(_TCHAR* names,_TCHAR* selectedName,_TCHAR* desc);

Parámetros

namesPuntero a una zona de memoria donde se almacenan los nombres de losadaptadores de red disponibles en el sistema. Los nombres se encuentranseparados por el carácter nulo genérico, TEXT(‘\0’), y termina con dos nulosseguidos.

selectedNamePuntero a una zona de memoria donde la función almacena el nombre deladaptador seleccionado por el usuario.

descPuntero a una zona de memoria donde se almacenan las descripciones de losadaptadores de red disponibles en el sistema. Las descripciones se almacenan enel mismo orden que los nombres, separados por un carácter nulo genérico,TEXT(‘\0’), y termina con dos nulos seguidos.

Valor de retorno

Devuelve 0 si el usuario no ha seleccionado ningún adaptador. Devuelve un númerocomprendido entre 1 y el número de adaptadores existentes en el sistema si el usuario haelegido alguno de ellos.


Observaciones

Los parámetros names y desc pueden obtenerse con una llamada a la funciónNepalGetAvailAdapterNames. En caso de que el usuario seleccione un adaptador, lavariable selectedName contiene el nombre del adaptador seleccionado, que puedeutilizarse directamente en la llamada a la función NepalOpenAdapter para abrir eladaptador correspondiente.

Dado que la interfaz de usuario es en modo carácter (un menú en pantalla), la funciónsólo puede utilizarse en aplicaciones Win32 en modo consola.

Portabilidad

Soportado en Windows NT y Windows 9X para aplicaciones en modo consola.

Véase también

NepalSelectAdapter, NepalOpenAdapter

5.6 Conversión y comparación

• ETH_COMPARE_NETWORK_ADDRESSES_EQ

Esta macro compara dos direcciones Ethernet, determinando si son iguales o no.

ETH_COMPARE_NETWORK_ADDRESSES_EQ(_A, _B, _Result)

Parámetros

AUna dirección Ethernet, definida del tipo ETHERNET_ADDRESS.

BUna dirección Ethernet, definida del tipo ETHERNET_ADDRESS.

_ResultEs un parámetro de salida. En el parámetro _Result almacena el valor lógicoTRUE si ambas direcciones son distintas. Almacena el valor lógico FALSE siambas direcciones son iguales.


Valor de retorno

Ninguno (véase el parámetro _Result).

Observaciones

Ninguna.

Portabilidad


Véase también

ETHERNET_ADDRESS

• ETH_IS_MULTICAST

La macro ETH_IS_MULTICAST sirve para determinar si una dirección Ethernet es detipo multicast.

ETH_IS_MULTICAST(Address)

Parámetros

AddressUna dirección Ethernet, definida del tipo ETHERNET_ADDRESS.

Valor de retorno

La macro devuelve TRUE si la dirección Ethernet es de tipo multicast. DevuelveFALSE en caso contrario.

Observaciones

Las direcciones Ethernet multicast se caracterizan por que su byte más significativotiene el valor 0x01.

Portabilidad



Véase también

ETHERNET_ADDRESS

• INV

Esta macro invierte la posición de los bytes de una palabra, sustituye el byte mássignificativo por el valor del byte menos significativo y el valor de éste por el anterior.

INV(w)

Parámetros

WUna variable de tipo palabra (WORD) de 16 bits (2 bytes). Es un parámetro deentrada y salida, el resultado queda almacenado en la misma variable.

Valor de retorno

Ninguno (el resultado lo almacena en el parámetro W).

Observaciones

Ninguna.

Portabilidad


Véase también


• NepalEther2Byte

La función NepalEther2Byte crea una dirección Ethernet en representación de bytes apartir de una representación de caracteres genéricos.

BOOLEAN __stdcall NepalEther2Byte(_TCHAR* dir,ETHERNET_ADDRESS dirEth);

Parámetros

dirUna dirección Ethernet, almacenada en un array de caracteres genéricos.

dirEthUna dirección Ethernet, definida del tipo ETHERNET_ADDRESS.

Valor de retorno

La función devuelve TRUE si ha podido convertir la dirección. Devuelve FALSE encaso contrario.

Observaciones

La función admite direcciones Ethernet expresadas en caracteres genéricos de la forma

TEXT(“ff:02:f5:A3:9b:EF”)

Portabilidad


Véase también

ETHERNET_ADDRESS, NepalIP2Byte


• NepalIP2Byte

La función NepalIP2Byte crea una dirección IP en representación de bytes a partir deuna representación de caracteres genéricos.

BOOLEAN __stdcall NepalIP2Byte(_TCHAR* dir,IP_ADDRESS dirIP);

Parámetros

dirUna dirección IP, almacenada en un array de caracteres genéricos.

dirIPUna dirección IP, definida del tipo IP_ADDRESS.

Valor de retorno

La función devuelve TRUE si ha podido convertir la dirección. Devuelve FALSE encaso contrario.

Observaciones

La función admite direcciones Ethernet expresadas en caracteres genéricos de la forma

TEXT(“172.16.0.1”)

Portabilidad


1.1.1.2 Véase también

IP_ADDRESS, NepalEther2Byte


5.7 Impresión de resultados

Las siguientes funciones imprimen en modo consola distintos tipos de información ensu formato más adecuado. Son utilizables únicamente en aplicaciones en modo consola(MS-DOS sobre Win32).

• NepalWriteEtherAddressImprime por pantalla una dirección Ethernet en su formato estándar.

• NepalWriteEtherFrameImprime por pantalla con formato el contenido de una trama Ethernet,completa sólo las primeras líneas.

• NepalWriteFilterImprime por pantalla el nombre de las constantes de filtro de direccióncorrespondientes a un valor determinado.

• NepalWriteInfoImprime por pantalla con formato todos los campos de una estructuraADAPTER_INFO.

• NepalWriteIPAddressImprime por pantalla una dirección IP en su formato estándar.

• NepalWriteOidListImprime por pantalla los nombres de las constantes correspondientes a OIDsde una lista de valores.

• NepalWriteMediaListImprime por pantalla los nombres de las constantes correspondientes amedios de transmisión, almacenados en una lista.

• NepalWriteStateImprime por pantalla el nombre del estado del adaptador correspondiente alvalor.

• NepalWriteGenMacOptionsImprime por pantalla las opciones genéricas del adaptador.

• NepalWriteMacOptionsImprime por pantalla las opciones del adaptador.

• PAUSAEsta macro imprime un mensaje por pantalla y detiene la ejecución delprograma hasta que el usuario pulsa cualquier tecla.


5.8 Tipos y estructuras de datos

Se muestran a continuación los tipos y estructuras de datos definidos en NEPAL.

• ADAPTER

typedef struct _ADAPTER{

HANDLE hFile;_TCHAR SymbolicLink[ MAX_LINK_NAME_LENGTH ];BYTE CurrentAddress[ ETHERNET_ADDRESS_LENGTH ];BYTE PermanentAddress[ ETHERNET_ADDRESS_LENGTH ];ULONG ulMaxFrameSize;ULONG ulMaxLookAheadSize;

}ADAPTER, *LPADAPTER;

• ADAPTER_INFOtypedef struct _ADAPTER_INFO {1//Características operacionales2generales3

4//OID_GEN_SUPPORTED_LIST, (cofificado)5ULONG6GenSupportedList[NEPAL_SUPPORTED_OIDS];7int nGenSupportedList;8//OID_GEN_HARDWARE_STATUS,9NDIS_HARDWARE_STATUS GenHardwareStatus;10BOOL bGenHardwareStatus;11//OID_GEN_MEDIA_SUPPORTED, (cofificado)12NDIS_MEDIUM13GenMediaSupported[NUM_LISTA_MEDIA];14int nGenMediaSupported;15//OID_GEN_MEDIA_IN_USE, (cofificado)16ULONG GenMediaInUse[NUM_LISTA_MEDIA];17int nGenMediaInUse;18//OID_GEN_MAXIMUM_LOOKAHEAD,19ULONG GenMaxLookahead;20BOOL bGenMaxLookahead;21//OID_GEN_MAXIMUM_FRAME_SIZE,22ULONG GenMaxFrameSize;23BOOL bGenMaxFrameSize;24//OID_GEN_LINK_SPEED,25ULONG GenLinkSpeed;26BOOL bGenLinkSpeed;27//OID_GEN_TRANSMIT_BUFFER_SPACE,28ULONG GenTransmitBufferSpace;29BOOL bGenTransmitBufferSpace;30//OID_GEN_RECEIVE_BUFFER_SPACE,31ULONG GenReceiveBufferSpace;32BOOL bGenReceiveBufferSpace;33//OID_GEN_TRANSMIT_BLOCK_SIZE,34ULONG GenTransmitBlockSize;35BOOL bGenTransmitBlockSize;36//OID_GEN_RECEIVE_BLOCK_SIZE,37ULONG GenReceiveBlockSize;38BOOL bGenReceiveBlockSize;39//OID_GEN_VENDOR_ID,40UCHAR GenVendorId[NUM_VENDOR_ID];41BOOL bGenVendorId;42//OID_GEN_VENDOR_DESCRIPTION,43

UCHAR44GenVendorDescription[MAX_VENDOR_DESC_LEN45GTH];46BOOL bGenVendorDescription;47//OID_GEN_VENDOR_DRIVER_VERSION,48USHORT GenVendorDriverVersionMajor;49USHORT GenVendorDriverVersionMinor;50BOOL bGenVendorDriverVersion;51//OID_GEN_CURRENT_PACKET_FILTER,52(cofificado)53ULONG GenCurrentPacketFilter;54BOOL bGenCurrentPacketFilter;55//OID_GEN_CURRENT_LOOKAHEAD,56ULONG GenCurrentLookahead;57BOOL bGenCurrentLookahead;58//OID_GEN_DRIVER_VERSION,59BYTE GenDriverVersionMajor;60BYTE GenDriverVersionMinor;61BOOL bGenDriverVersion;62//OID_GEN_MAXIMUM_TOTAL_SIZE,63ULONG GenMaxTotalSize;64BOOL bGenMaxTotalSize;65//OID_GEN_PROTOCOL_OPTIONS, (cofificado)66(tipo set solo)67ULONG GenProtOptions;68BOOL bGenProtOptions;69//OID_GEN_MAC_OPTIONS, (cofificado)70ULONG GenMacOptions;71BOOL bGenMacOptions;72//OID_GEN_MEDIA_CONNECT_STATUS73ULONG GenMediaConnectStatus;74BOOL bGenMediaConnectStatus;75//OID_GEN_MAXIMUM_SEND_PACKETS76ULONG GenMaxSendPackets;77BOOL bGenMaxSendPackets;78

79//Estadísticas Generales80

81//OID_GEN_XMIT_OK,82ULONG GenXmitOk;83BOOL bGenXmitOk;84//OID_GEN_RCV_OK,85ULONG GenRcvOk;86

47

BOOL bGenRcvOk;87//OID_GEN_XMIT_ERROR,88ULONG GenXmitError;89BOOL bGenXmitError;90//OID_GEN_RCV_ERROR,91ULONG GenRcvError;92BOOL bGenRcvError;93//OID_GEN_RCV_NO_BUFFER,94ULONG GenRcvNoBuffer;95BOOL bGenRcvNoBuffer;96//OID_GEN_DIRECTED_BYTES_XMIT,97_int64 GenDirectedBytesXmit;98BOOL bGenDirectedBytesXmit;99//OID_GEN_DIRECTED_FRAMES_XMIT,100ULONG GenDirectedFramesXmit;101BOOL bGenDirectedFramesXmit;102//OID_GEN_MULTICAST_BYTES_XMIT,103_int64 GenMulticastBytesXmit;104BOOL bGenMulticastBytesXmit;105//OID_GEN_MULTICAST_FRAMES_XMIT,106ULONG GenMulticastFramesXmit;107BOOL bGenMulticastFramesXmit;108//OID_GEN_BROADCAST_BYTES_XMIT,109_int64 GenBroadcastBytesXmit;110BOOL bGenBroadcastBytesXmit;111//OID_GEN_BROADCAST_FRAMES_XMIT,112ULONG GenBroadcastFramesXmit;113BOOL bGenBroadcastFramesXmit;114//OID_GEN_DIRECTED_BYTES_RCV,115_int64 GenDirectedBytesRcv;116BOOL bGenDirectedBytesRcv;117//OID_GEN_DIRECTED_FRAMES_RCV,118ULONG GenDirectedFramesRcv;119BOOL bGenDirectedFramesRcv;120//OID_GEN_MULTICAST_BYTES_RCV,121_int64 GenMulticastBytesRcv;122BOOL bGenMulticastBytesRcv;123//OID_GEN_MULTICAST_FRAMES_RCV,124ULONG GenMulticastFramesRcv;125BOOL bGenMulticastFramesRcv;126//OID_GEN_BROADCAST_BYTES_RCV,127_int64 GenBroadcastBytesRcv;128BOOL bGenBroadcastBytesRcv;129//OID_GEN_BROADCAST_FRAMES_RCV,130ULONG GenBroadcastFramesRcv;131BOOL bGenBroadcastFramesRcv;132//OID_GEN_RCV_CRC_ERROR,133ULONG GenRcvCrcError;134BOOL bGenRcvCrcError;135//OID_GEN_TRANSMIT_QUEUE_LENGTH,136ULONG GenTransmitQueueLength;137BOOL bGenTransmitQueueLength;138

139//características operacionales ethernet140

141//OID_802_3_PERMANENT_ADDRESS,142BYTE PermanentAddress[143ETHERNET_ADDRESS_LENGTH ];144BOOL bPermanentAddress;145//OID_802_3_CURRENT_ADDRESS,146BYTE CurrentAddress[147ETHERNET_ADDRESS_LENGTH ];148BOOL bCurrentAddress;149//OID_802_3_MULTICAST_LIST,150ETHERNET_ADDRESS151MulticastList[MAX_MC_LIST];152int nMulticastList;153//OID_802_3_MAXIMUM_LIST_SIZE,154ULONG MaxListSize;155BOOL bMaxListSize;156//OID_802_3_MAC_OPTIONS157ULONG MacOptions;158BOOL bMacOptions;159

160//estadísticas ethernet161

162//OID_802_3_RCV_ERROR_ALIGNMENT,163

ULONG RcvErrorAlignment;164BOOL bRcvErrorAlignment;165//OID_802_3_XMIT_ONE_COLLISION,166ULONG XmitOneCollision;167BOOL bXmitOneCollision;168//OID_802_3_XMIT_MORE_COLLISIONS,169ULONG XmitMoreCollisions;170BOOL bXmitMoreCollisions;171//OID_802_3_XMIT_DEFERRED,172ULONG XmitDeferred;173BOOL bXmitDeferred;174//OID_802_3_XMIT_MAX_COLLISIONS,175ULONG XmitMaxCollisions;176BOOL bXmitMaxCollisions;177//OID_802_3_RCV_OVERRUN,178ULONG RcvOverrun;179BOOL bRcvOverrun;180//OID_802_3_XMIT_UNDERRUN,181ULONG XmitUnderrun;182BOOL bXmitUnderrun;183//OID_802_3_XMIT_HEARTBEAT_FAILURE,184ULONG XmitHeartbeatFailure;185BOOL bXmitHeartbeatFailure;186//OID_802_3_XMIT_TIMES_CRS_LOST,187ULONG XmitTimesCrsLost;188BOOL bXmitTimesCrsLost;189//OID_802_3_XMIT_LATE_COLLISIONS190ULONG XmitLateCollisions;191BOOL bXmitLateCollisions;192//OID_GEN_PROT_RESET193BOOL bGenProtReset;194//OID_GEN_PROT195WORD GenProt;196BOOL bGenProtSet;197BOOL bGenProt;198

199} ADAPTER_INFO,*PADAPTER_INFO;200

48

• ETHERNET_FRAME

typedef struct _ETHERNET_FRAME{

BYTE DestinationAddress[ ETHERNET_ADDRESS_LENGTH ];BYTE SourceAddress[ ETHERNET_ADDRESS_LENGTH ];WORD Protocol;BYTE Data[ETHERNET_PACKET_LENGTH - ETHERNET_HEADER_LENGTH];

}ETHERNET_FRAME, *LPETHERNET_FRAME;

• ETHERNET_ADDRESS

typedef BYTE ETHERNET_ADDRESS[ ETHERNET_ADDRESS_LENGTH ];

• IP_ADDRESS

typedef BYTE IP_ADDRESS [ IP_ADDRESS_LENGTH ];

• PACKET

typedef struct _PACKET{

HANDLE hEvent;OVERLAPPED OverLapped;PVOID Buffer;UINT Length;ULONG ulBytesReceived;BOOLEAN bIoComplete;

}PACKET, *LPPACKET;

• NepalGlobalSupportedOids

Con este tipo de datos se definen el conjunto de valores que se muestra en la siguientetabla, junto con su correspondiente significado.

49

Valores

En la siguiente tabla, la columna “Valor” indica el nombre del OID y la columna “L” indicala longitud en bytes de la información intercambiada con el controlador utilizando dichoOID.

La columna “Q” puede tener una “M” (Mandatory) o una “O” (Optional). Una “M” indicaque el OID puede utilizarse en solicitudes de información al controlador. Una “O” indicaque el OID se puede utilizar en solicitudes de información al controlador siempre que elcontrolador soporte el objeto referido.

La columna “S” es equivalente a la columna “Q” salvo que se refiere a operaciones deconfiguración de información en el controlador.

Valor L Q S Significado

CARACTERÍSTICASOPERATIVAS GENERALESOID_GEN_SUPPORTED_LIST Arr(4) M Lista de OIDs soportadosOID_GEN_HARDWARE_STATUS 4 M Estado del hardwareOID_GEN_MEDIA_SUPPORTED Arr(4) M Tipos de medios soportadosOID_GEN_MEDIA_IN_USE Arr(4) M Tipos de medios en usoOID_GEN_MAXIMUM_LOOKAHEAD 4 M Tamaño máximo en bytes de la recepción

lookaheadOID_GEN_MAXIMUM_FRAME_SIZE 4 M Tamaño máximo en bytes de la tramaOID_GEN_LINK_SPEED 4 M Velocidad del enlace en unidades de 100

bpsOID_GEN_TRANSMIT_BUFFER_SPACE 4 M Espacio del buffer de transmisiónOID_GEN_RECEIVE_BUFFER_SPACE 4 M Espacio del buffer de recepciónOID_GEN_TRANSMIT_BLOCK_SIZE 4 M Cantidad mínima de almacenamiento en

bytes que una trama individual ocupa enel buffer de transmisión del adaptador

OID_GEN_RECEIVE_BLOCK_SIZE 4 M Cantidad mínima de almacenamiento enbytes que una trama individual ocupa enel buffer de recepción del adaptador

OID_GEN_VENDOR_ID 4 M Código del fabricante del adaptador dered

OID_GEN_VENDOR_DESCRIPTION Var. M Descripción de la tarjeta de red,proporcionada por el fabricante

OID_GEN_VENDOR_DRIVER_VERSION 4 M Número de versión del controlador deladaptador asignado por el fabricante

OID_GEN_CURRENT_PACKET_FILTER 4 M M Filtro de dirección activoOID_GEN_CURRENT_LOOKAHEAD 4 M M Tamaño del lookahead activoOID_GEN_DRIVER_VERSION 2 M Número de versión NDIS que utiliza el

controladorOID_GEN_MAXIMUM_TOTAL_SIZE 4 M Longitud máxima en bytes de la tramaOID_GEN_PROTOCOL_OPTIONS 4 M Opciones de protocolo adicionalesOID_GEN_MAC_OPTIONS 4 M Opciones del adaptador adicionalesOID_GEN_MEDIA_CONNECT_STATUS 4 M Indica si el adaptador está conectado a

la redOID_GEN_MAXIMUM_SEND_PACKETS 4 M El número máximo de tramas a enviar que

el controlador puede aceptar en cadallamada a su función“MiniportSendPackets”

50

ESTADÍSTICAS GENERALESOID_GEN_XMIT_OK 4 M Tramas enviadas sin erroresOID_GEN_RCV_OK 4 M Tramas recibidas sin erroresOID_GEN_XMIT_ERROR 4 M Tramas no transmitidas o transmitidas

con erroresOID_GEN_RCV_ERROR 4 M Tramas recibidas con erroresOID_GEN_RCV_NO_BUFFER 4 M Tramas perdidas por falta de buffersOID_GEN_DIRECTED_BYTES_XMIT 8 O Bytes transmitidos sin errores a

direccionesOID_GEN_DIRECTED_FRAMES_XMIT 4 O Tramas transmitidas sin errores a

direccionesOID_GEN_MULTICAST_BYTES_XMIT 8 O Bytes transmitidos sin errores a

direcciones multicastOID_GEN_MULTICAST_FRAMES_XMIT 4 O Tramas transmitidas sin errores a

direcciones multicastOID_GEN_BROADCAST_BYTES_XMIT 8 O Bytes transmitidos sin errores a

direcciones broadcastOID_GEN_BROADCAST_FRAMES_XMIT 4 O Tramas transmitidas sin errores a

direcciones broadcastOID_GEN_DIRECTED_BYTES_RCV 8 O Bytes recibidos sin errores a

direccionesOID_GEN_DIRECTED_FRAMES_RCV 4 O Tramas recibidas sin errores a

direccionesOID_GEN_MULTICAST_BYTES_RCV 8 O Bytes recibidos sin errores a

direcciones multicastOID_GEN_MULTICAST_FRAMES_RCV 4 O Tramas recibidas sin errores a

direcciones multicastOID_GEN_BROADCAST_BYTES_RCV 8 O Bytes recibidos sin errores a

direcciones broadcastOID_GEN_BROADCAST_FRAMES_RCV 4 O Tramas recibidas sin errores a

direcciones broadcastOID_GEN_RCV_CRC_ERROR 4 O Tramas recibidas con error CRC o FCSOID_GEN_TRANSMIT_QUEUE_LENGTH 4 O Longitud de la cola de transmisiónOBJETOS ETHERNETOID_802_3_PERMANENT_ADDRESS 6 M Dirección permanenteOID_802_3_CURRENT_ADDRESS 6 M Dirección actualOID_802_3_MULTICAST_LIST Arr(6) M M Lista actual de direcciones multicastOID_802_3_MAXIMUM_LIST_SIZE 4 M Tamaño máximo de la lista de direcciones

multicastOID_802_3_MAC_OPTIONS 4 M Opciones del adaptador de red

ESTADÍSTICAS ETHERNETOID_802_3_RCV_ERROR_ALIGNMENT 4 M Tramas recibidas con error de

alineamientoOID_802_3_XMIT_ONE_COLLISION 4 M Tramas enviadas con una colisiónOID_802_3_XMIT_MORE_COLLISIONS 4 M Tramas enviadas con mas de una colisiónOID_802_3_XMIT_DEFERRED 4 O Tramas enviadas después de ser aplazadasOID_802_3_XMIT_MAX_COLLISIONS 4 O Tramas no enviadas debido a colisionesOID_802_3_RCV_OVERRUN 4 O Tramas no recibidas debido a errores de

sobrecarga (overrun) del adaptadorOID_802_3_XMIT_UNDERRUN 4 O Tramas no recibidas debido a errores de

underrun del adaptadorOID_802_3_XMIT_HEARTBEAT_FAILURE

4 O Tramas enviadas con éxito sin ladetección de colisión (collision-detectheartbeat)

OID_802_3_XMIT_TIMES_CRS_LOST 4 O Veces que se perdió la portadora durantela transmisión

OID_802_3_XMIT_LATE_COLLISIONS 4 O Número de colisiones detectadas despuésde la ventana normal

ESPECÍFICOS DE NEPALOID_GEN_PROT_RESET 0 O Desactivación del filtro de protocoloOID_GEN_PROT 2 O O Activación/consulta del filtro de

protocolo

Tabla 2 Lista de OIDs disponibles.

52

5.9 Constantes

Se listan a continuación las constantes definidas en el fichero “nepal.h”, los valores quetoman y una breve descripción de su significado.

ETHERNET_ADDRESS_LENGTH 6

Indica la longitud en bytes de una dirección Ethernet.

ETHERNET_PACKET_LENGTH 1514

Indica la longitud máxima en bytes de una trama Ethernet.

ETHERNET_HEADER_LENGTH 14

Indica la longitud en bytes de la cabecera de las tramas Ethernet.

IP_ADDRESS_LENGTH 4

Indica la longitud en bytes de una dirección IP.

MAX_MC_LIST 64

Indica el número máximo de direcciones Ethernet multicast que puede almacenarNEPAL en la lista de direcciones multicast.

MAX_LINK_NAME_LENGTH 64

Indica la longitud en caracteres, char o wchar, de un nombre de adaptador.

MAX_ADAPTERS 24

Indica el número máximo de adaptadores de red instalados en un equipo que puedemanejar NEPAL.

NEPAL_SUPPORTED_OIDS 58

Indica el número total de OID definidos. Cada vez que se defina uno se debeincrementar el valor de esta constante.

53

6. Desarrollo de protocolos sobre NEPAL.

El API NEPAL permite la transmisión y recepción de tramas Ethernet. Con objeto dedesarrollar protocolos sobre dicho API, el programador deberá pasar para la transmisión yrecibir para la recepción tramas ethernet en las cuales no existira el campo de preámbulo yel campo de CRC. El resto de campos deben ser codificados. Estos dos campos sonañadidos por el hardware antes del envío de la trama y eliminados en la recepción.

El formato de la trama Ethernet se muestra en la Figura 2.

Figura 2 : Formato de Trama Ethernet

Al recibir una trama Ethernet, la tarjeta de red comprueba el CRC. En caso de detectarerrores, la trama es eliminada, en caso de transmisión sin errores la trama es entregada alsoftware de red correspondiente. Para ello, la librería analiza el campo “tipo de protocolo”para ver a que protocolo de nivel superior debe reenviar dicha trama. Los valores asociadosa este campo están normalizados [RFC1700]. Entre los valores (protocolos) más usadostenemos 0x8001 para el protocolo IP versión 4 y 0x8061 para el protocolo de resolución dedirecciones ARP.

Dentro de una misma maquina pueden coexistir distintas tarjetas de red (ej: routers,bridges, etc). Estas tarjetas son identificadas NEPAL tal como se describe en el manual dereferencia y debe ser tenida en cuenta a la hora de transmitir y recibir tráfico.

1 Estos valores se expresan en hexadecimal y en el estilo de “Lenguaje C”. En el resto de la documentación seutilizará esta notación.

LABORATORIO DE TELEMATICA Guia de Referencia del API...

Documents

Transcript of LABORATORIO DE TELEMATICA Guia de Referencia del API...