DosConnectNPipe

---

DosConnectNPipe prepara un named pipe para aceptar peticiones DosOpen desde un cliente. Si el extremo del cauce ya estaba abierto, DosConnectNPipe retorna inmediatamente. Si no es así, depende del modo en que haya sido definida. Si es blocking, el proceso servidor se congela hasta que un cliente habra el cauce; si es nonblocking, retorna inmediatamente con el error Cauce no abierto. Si el cauce fue abierto y luego cerrado por un cliente, pero no ha sido desconectado con DosDisConnectNPipe por el servidor, retorna un error El cauce está cerrado (Error_Broken_Pipe). Si es un cliente quien ejecuta esta llamada, se devuelve el error Cauce incorrecto.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
APIRET rc; /* Codigo de error */

rc = DosConnectNPipe(hpipeHandle);

||

Parámetros

|| || hpipeHandle || El handle de un named pipe a ser activado (devuelto al proceso servidor por DosCreateNPipe). ||

||

Codigos de error

|| || || Sin error ||
|| 95 || Interrupción ||
|| 109 || El cauce (pipe) está cerrado ||
|| 230 || Cauce incorrecto ||
|| 233 || Cauce no abierto ||





DosCreateNPipe crea un named pipe.

#define INCL_BASE
#include <os2.h>

PSZ pszFileName;
PHPIPE phpipePipeHandle;
ULONG ulOpenMode;
ULONG ulPipeMode;
ULONG ulOutBufSize;
ULONG ulInBufSize;
ULONG ulTimeOut;
APIRET rc; /* Codigo de error */

rc = DosCreateNPipe(pszFileName, phpipePipeHandle, ulOpenMode, ulPipeMode, ulOutBufSize, ulInBufSize, ulTimeOut);

||

Parámetros

|| || pszFileName || Puntero a una cadena de caracteres con el nombre del cauce a crear. Es necesario que comience con el prefijo \PIPE\ y cumplir las normas de nombres del sistema de archivos. ||
|| phpipePipeHandle || Un puntero a una zona de memoria donde OS/2 devolverá un handle al cauce que estamos creando. ||
|| ulOpenMode || Una variable cuyos bits tienen el siguiente significado: ||
|| || || Bit || Descripción || || 31-16 || Reservado || || 15 || Reservado. Tiene que ser 0. || || 14 || Write-through. Tiene sentido en el caso de cauces remotos (en otro sistema conectado en red). Si es 0, los datos a enviar pueden ser almacenados en un buffer con el fin de enviarlos todos juntos. Si es 1, los datos serán enviados inmediatamente. || || 13-8 || Reservado || || 7 || Bit de herencia. Si es 0, el cauce pertenecerá también a los procesos hijos. Si es 1, será un cauce privado, y no será heredado por ningún hijo. || || 6-3 || Reservado. Tiene que valer 0. || || 2-0 || Modo de acceso. Indica el sentido de los datos:
000 = (NP_ACCESS_INBOUND) cauce de entrada (del cliente al servidor).
001 = (NP_ACCESS_OUTBOUND) cauce de salida (del servidor al cliente).
010 = (NP_ACCESS_DUPLEX) cauce bidireccional (de cliente a servidor y viceversa). Cualquier otro valor no será válido. || ||
|| ulPipeMode || Sus bits tienen los siguientes significados: ||
|| || || Bit || Descripción || || 31-16 || Reservado. || || 15 || Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error. || || 14-12 || Reservado. || || 11-10 || Tipo de cauce.
00 = (NP_TYPE_BYTE) El cauce está orientado a byte. Esto es, los datos son escritos como una ráfaga de bytes, y recuperados de igual forma.
01 = (NP_TYPE_MESSAGE) El cauce está orientado a mensajes. Esto es, cada vez que se escribe algo, el sistema recuerda su longitud, y al recuperarlo devuelve exactamente el mismo número de bytes introducidos de cada vez. Esto lo almacena en los dos primeros bytes del mensaje (cabecera del mensaje). Una cabecera de ceros está reservada, y no se admiten mensajes de longitud cero. || || 9-8 || Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes. || || 7-0 || ICount (Instance Count). Cuando la primera instancia de una named pipe es creada, ICount especifica cuantas instancias serán creadas. El número de instancias determina cuantos clientes se pueden atender a la vez. Si se intentan definir más instancias de las posibles, se devuelve un error. Los posibles valores son:
1 : Solo se admite una instancia (la actual).
1 < n < 255 : Se admiten n instancias.

---

1 : Se admiten ilimitadas instancias.
0 : reservado. || || || ulOutBufSize || Número de bytes que debe reservar OS/2 para el buffer de salida (servidor a cliente). ||
|| ulInBufSize || Número de bytes que debe reservar OS/2 para el buffer de entrada (cliente a servidor). ||
|| ulTimeOut || El valor por defecto para el TimeOut de DosWaitNPipe. Solo se tiene que especificar en la primera instancia. Si se especifica 0, se toma el valor por defecto de 50 milisegundos. ||

||

Codigos de error

|| || || Sin error ||
|| 3 || Path no encontrado ||
|| 8 || No hay suficiente memoria ||
|| 84 || Fuera de las estructuras (error interno) ||
|| 87 || Parámetro no válido ||
|| 231 || Cauce (pipe) ocupado. ||





DosCreatePipe crea un cauce sin nombre (unnamed pipe).

#define INCL_BASE
#include <os2.h>

PHFILE pshfReadHandle;
PHFILE pshfWriteHandle;
ULONG ulPipeSize;
APIRET rc; /* Codigo de error */

rc = DosCreatePipe(pshfReadHandle, pshfWriteHandle, ulPipeSize);

||

Parámetros

|| || pshfReadHandle || Un puntero a una doble palabra donde OS/2 devolverá el handle de lectura para el cauce. Este handle deberá ser usado por el proceso que quiera leer del cauce. ||
|| pshfWriteHandle || Un puntero a una doble palabra donde OS/2 devolverá el handle de escritura para el cauce. Este handle deberá ser usado por el proceso que quiera escribir en el cauce. ||
|| ulPipeSize || El tamaño en bytes del buffer del cauce. ||

||

Codigos de error

|| || || Sin error ||
|| 8 || No hay suficiente memoria ||





DosDisConnectNPipe sirve de acuse de recibo para un proceso que ha cerrado un named pipe. Mientras el servidor no ejecute esta llamada (sobre un cauce cerrado por un cliente) recibirá un valor de cero en BytesRead si intenta leer, o un error BROKEN_PIPE (el cauce está cerrado, error 109) si intenta escribir. El cauce no puede ser usado por otro cliente hasta que el servidor ejecute DosConnectNPipe. DosDisConnectNPipe también libera todos los threads bloqueados en un DosRead.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
APIRET rc; /* Codigo de error */

rc = DosDisConnectNPipe(hpipeHandle);

||

Parámetros

|| || hpipeHandle || Handle de un named pipe a desconectar. ||

||

Codigos de error

|| || || Sin error ||
|| 109 || El cauce (pipe) está cerrado ||
|| 230 || Cauce incorrecto ||





DosDupHandle obtiene un nuevo handle para un fichero ya abierto, de modo que se puede usar cualquiera de los dos para referirse a él. El uso de DosClose sobre un handle no afectará al handle duplicado.

#define INCL_BASE
#include <os2.h>

HFILE OldFileHandle;
PHFILE pshfNewFileHandle;
APIRET rc; /* Codigo de error */

rc = DosDupHandle(OldFileHandle, pshfNewFileHandle);

||

Parámetros

|| || OldFileHandle || Handle del fichero o cauce a duplicar. ||
|| pshfNewFileHandle || Puntero a una doble palabra. Si al hacer la llamada contiene 0xFFFFFFFF, OS/2 devolverá el primer valor libre que haya. Si contiene un valor distinto, asociará el fichero con ese número. Por ejemplo, si como valor introducimos 0, OS/2 asociará la entrada estandar del sistema al fichero/cauce indicado en OldFileHandle; si vale 1, OS/2 asociará la salida estandar del sistema, y si vale 2, OS/2 asociará la salida de error estandar. Si el nuevo handle indicado es igual al de algún fichero abierto, OS/2 lo cerrará primero. ||

||

Codigos de error

|| || || Sin error ||
|| 4 || Demasiados archivos abiertos ||
|| 6 || HANDLE no válido ||
|| 114 || El handle de destino no es válido ||





DosPeekNPipe permite examinar el dato en un named pipe sin eliminarlo. También devuelve información sobre el estado del cauce. Esta función nunca se bloquea; siempre retorna inmediatamente. El valor del estado puede ser usado por el cliente o el servidor para tomar la acción adecuada.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
PVOID pBuffer;
ULONG ulBufferLen;
PULONG pBytesRead;
PAVAILDATA pBytesAvail;
PULONG pPipeState;
APIRET rc; /* Codigo de error */

rc = DosPeekNPipe(hpipeHandle, pBuffer, ulBufferLen, pBytesRead, pBytesAvail, pPipeState);

||

Parámetros

|| || hpipeHandle || Handle del named pipe a examinar. DosCreateNPipe devuelve el handle del servidor; DosOpen devuelve el handle del cliente. ||
|| pBuffer || Un puntero al buffer de salida. ||
|| ulBufferLen || Número de bytes a leer del cauce. ||
|| pBytesRead || Un puntero a una posición de memoria donde OS/2 devolverá el número de bytes leidos. ||
|| pBytesAvail || Un puntero a una zona de memoria de 4 bytes donde OS/2 devolverá el número de bytes que están disponibles en el cauce. La estructura del buffer es: ||
|| || || Bit || Descripción || || 32-16 || Número de bytes que contiene el buffer del cauce (incluyendo bytes de cabecera y bytes que ya han sido examinados). || || 15-0 || Número de bytes que componen el mensaje actual (0 para un cauce orientado a byte). || ||
|| pPipeState || Un puntero a una posición de memoria donde OS/2 devolverá el estado del cauce ||
|| || || Valor || Significado || || 1 || (NP_STATE_DISCONNECTED) Desconectado || || 2 || (NP_STATE_LISTENING) En escucha || || 3 || (NP_STATE_CONNECTED) Conectado || || 4 || (NP_STATE_CLOSING) Cerrándose ||
El cauce está desconectado inmediatamente después de una llamada a DosCreateNPipe o a DosDisConnectNPipe.
El cauce está en escucha después de que el servidor ejecute DosConnectNPipe.
El cauce está conectado después de que un cliente haya ejecutado con éxito DosOpen.
El cauce está cerrándose después de que un cliente haya ejecutado DosClose al handle del cauce y a todos sus duplicados. ||

||

Codigos de error

|| || || Sin error ||
|| 230 || Cauce incorrecto ||
|| 231 || Cauce (pipe) ocupado. ||
|| 233 || Cauce no abierto ||





DosQueryNPHState devuelve información sobre un named pipe.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
PULONG pPipeHandleState;
APIRET rc; /* Codigo de error */

rc = DosQueryNPHState(hpipeHandle, pPipeHandleState);

||

Parámetros

|| || hpipeHandle || El handle del named pipe a comprobar. ||
|| pPipeHandleState || Un puntero a una posición de memoria donde OS/2 devolverá el estado del cauce. ||
|| || || Bit || Descripción || || 31-16 || Reservado. || || 15 || Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error. || || 14 || Si es 0 (NP_END_CLIENT) el handle es para el cliente del cauce.
Si es 1 (NP_END_SERVER) el handle es para el servidor del cauce. || || 13-12 || Reservado. || || 11-10 || Tipo de cauce.
00 = (NP_TYPE_BYTE) El cauce está orientado a byte. Esto es, los datos son escritos como una ráfaga de bytes, y recuperados de igual forma.
01 = (NP_TYPE_MESSAGE) El cauce está orientado a mensajes. Esto es, cada vez que se escribe algo, el sistema recuerda su longitud, y al recuperarlo devuelve exactamente el mismo número de bytes introducidos de cada vez. Esto lo almacena en los dos primeros bytes del mensaje (cabecera del mensaje). Una cabecera de ceros está reservada, y no se admiten mensajes de longitud cero. || || 9-8 || Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes. || || 7-0 || ICount (Instance Count). Número de instancias. Determina cuantos clientes se pueden atender a la vez. Los posibles valores son:
1 : Solo se admite una instancia (la actual).
1 < n < 255 : Se admiten n instancias.

---

1 : Se admiten ilimitadas instancias.
0 : reservado. || ||
||

Codigos de error

|| || || Sin error ||
|| 230 || Cauce incorrecto ||
|| 233 || Cauce no abierto ||





DosSetNPHState permite cambiar el modo de bloqueo y de lectura de un named pipe.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
ULONG ulPipeHandleState;
APIRET rc; /* Codigo de error */

rc = DosSetNPHState(hpipeHandle, ulPipeHandleState);

||

Parámetros

|| || hpipeHandle || El handle del cauce a cambiar de estado. ||
|| ulPipeHandle || Un campo de bits con los siguientes significados: ||
|| || || Bit || Descripción || || 31-16 || Reservado. || || 15 || Modo de bloqueo.
0 = (NP_WAIT) Modo blocking. DosRead y DosWrite se congelan hasta que haya datos disponibles.
1 = (NP_NOWAIT) Modo nonblocking. DosRead y DosWrite retornan inmediatamente si no hay datos disponibles.
DosRead retorna un error No hay datos; DosWrite retorna 0 como cantidad de datos escritos si no queda sitio en el buffer del cauce. En caso contrario, no devuelve error. || || 14-10 || Reservado. || || 9-8 || Modo de lectura.
00 = (NP_READMODE_BYTE) Modo orientado a bytes. Lee el cauce como una ráfaga de bytes.
01 = (NP_READMODE_MESSAGE) Modo orientado a mensajes. Lee el cauce como un conjunto de mensajes.
Los cauces de mensaje pueden ser leidos tanto como mensajes como bytes; los cauces de bytes sólo pueden ser leidos como bytes. || || 7-0 || Reservado. Debe ser 0. || ||

||

Codigos de error

|| || || Sin error ||
|| 87 || Parámetro no válido ||
|| 230 || Cauce incorrecto ||
|| 231 || Cauce (pipe) ocupado. ||
|| 233 || Cauce no abierto ||





DosSetNPipeSem asocia a un named pipe un semáforo de evento compartido. Solo funciona con cauces locales. Si se intenta hacer con un cauce remoto (situado en otra máquina de la red) dará un error Función no válida. Si ya había un semáforo asociado al cauce, DosSetNPipeSem lo reemplaza con el nuevo semáforo.

#define INCL_BASE
#include <os2.h>

HPIPE hpipeHandle;
HSEM hsemSemHandle;
ULONG ulKeyHandle;
APIRET rc; /* Codigo de error */

rc = DosSetNPipeSem(hpipeHandle, hsemSemHandle, ulKeyHandle);

||

Parámetros

|| || hpipeHandle || El handle del cauce al que se le quiere asociar el semáforo de evento. ||
|| hsemSemHandle || El handle de un semafor de evento que es activado (posted) cuando el cauce tiene datos disponibles para leer o bien espacio disponible para escribir. ||
|| ulKeyHandle || Un valor que permite distinguir eventos provenientes de cauces distintos asociados al mismo semáforo. ||

||

Codigos de error

|| || || Sin error ||
|| 1 || Función no válida ||
|| 6 || HANDLE no válido ||
|| 87 || Parámetro no válido ||
|| 230 || Cauce incorrecto ||
|| 233 || Cauce no abierto ||





DosWaitNPipe espera a que haya disponible una instancia de un named pipe. Este caso se da cuando todas las posibles instancias de un cauce están ocupadas por procesos cliente. Solo se puede usar cuando DosOpen ha devuelto el error Cauce ocupado. Si DosWaitNPipe no devuelve error, el cliente debe repetir la llamada DosOpen para abrir el cauce. Si hay varios procesos esperando por una instancia libre de un mismo cauce, OS/2 se lo cederá primero al que tenga mayor prioridad; si dos tienen la misma prioridad, recibirá la instancia el que lleve más tiempo esperando.

#define INCL_BASE
#include <os2.h>

PSZ pszFileName;
ULONG ulTimeOut;
APIRET rc; /* Codigo de error */

rc = DosWaitNPipe(pszFileName, ulTimeOut);

||

Parámetros

|| || pszFileName || Puntero a una cadena ASCIIZ con el nombre del cauce a abrir. ||
|| ulTimeOut || El tiempo máximo, en milisegundos, que se esperará para que se libere una instancia del cauce. Cuando se indica un tiempo de 0, se usa el valor TimeOut definido en DosCreateNPipe. Cuando se indica un valor de -1, se espera un tiempo indefinido. ||

||

Codigos de error

|| || || Sin error ||
|| 2 || Fichero no encontrado ||
|| 95 || Interrupción ||
|| 231 || Cauce (pipe) ocupado. ||