System and methods for permitting access to a singular network process by multiple user processes6802065Abstract An application provides access by multiple user processes to a single network process. The application includes a socket library and a network process which contains the device driver software for a plurality of network devices and components. The socket library provides the interface mechanism to the network process and can be created as a static or dynamically linked library. All user processes access a singular network process by calling a function in the socket library. The socket library communicates with the network process by formatting a message containing all the information necessary for the network process to fulfill the intent of the API call. The network process sends a message that is received by the socket library which, in turn, transmits to the user process the return value and any data received from the network process. Claims What is claimed is: Description FIELD OF THE INVENTION
ipcStatus createMailbox(
DWORD /* messageSizeInBytes */, /*
unused for now */
DWORD queueSizeInMessages,
ipcMailboxHandle *handle);
Parameter Description
MessageSizeInBytes In one embodiment, only page sized
messages can be used with mailboxes.
QueueSizeInMessages The total number of pages/messages that
can be queued in the mailbox at any
particular time. This space comes out
of the callers RAM budget, which is
defined in the OS Integration Tool.
Handle Returned as a handle to the new mailbox
Returned Status:
Status Description
IpcValid The new mailbox was created
successfully.
IpcQuotaExceeded The maximum number of Mailboxes for the
process have already been created
OR
The maximum number of Envelopes for the
process have already been created
OR
The RAM needed to create the
queueSizeInMessages number of envelopes
was not available.
Warnings/Restrictions: When a mailbox is initially created, it contains no messages. When a mailbox is initially created, no other process in the system has the access rights necessary to send a message to it, including the creating process itself. Function: getMailboxHandle( ) 52--This function is used to obtain a handle to a "static" mailbox in a specified process. All static mailboxes for a process are automatically created by the OS when the process is started. This service provides the ability to get a mailbox handle from an integration time assigned mailbox name ID. The following routine illustrates the interface to the getMailboxHandle( ) 52 function:
ipcStatus getMailboxHandle(
DWORD mailboxName,
process_handle_t processHandle,
ipcMailboxHandle* handle );
Parameter Description
MailboxName The name of the mailbox assigned at
integration time via the OS Integration
Tool.
ProcessHandle Handle to the process which created
the mailbox.
Handle Returned is a handle to the mailbox.
Returned Status:
Status Description
IpcValid The mailbox was found in the
specified
process, and a handle to it was
returned.
IpcInvalid The static mailbox named mailboxName
does not exist in the specified
process.
IpcInvalidProcess- The specified process handle is
Handle invalid.
Warnings/Restrictions: There are no access rights checks when obtaining a mailbox handle. Access rights are only checked when sending or receiving messages via the returned handle. Function: grantMailboxAccess( ) 54--When a mailbox is initially created, the creating process is automatically granted read access to it. No process has write or send access to it. For a mailbox to be useful for interprocess communication, other processes must be allowed to send messages. This function is used to grant a specific process the ability to send messages to a mailbox created by the calling process. The following routine illustrates the interface with the grantMailboxAccess( ) 54 function:
ipcStatus grantMailboxAccess(
ipcMailboxHandle handle,
process_handle_t processHandle);
Parameter Description
Handle Handle to the mailbox for which
access is being granted.
ProcessHandle Handle to the process which will be
granted access to the mailbox.
Returned Status:
Status Description
ipcValid The specified access was granted to
the specified process.
IpcInvalidMailbox- The specified mailbox handle is not
Handle valid. It could have been modified
by the user inadvertently, or another
thread in the callers process could
have deleted the mailbox.
IpcInvalidProcess- The specified process handle is not
Handle valid. It could have been modified
by the user inadvertently, or the
process could have been deleted.
IpcInsufficient- The calling process is not the
Privilege process which created the mailbox.
Only the owner of a mailbox can
change the access rights.
Warnings/Restrictions: Only the process which owns a mailbox can change its access rights. Function: grantMailboxGlobalAccess( ) 56--When a mailbox is initially created, the creating process is automatically granted read access to it. No process has write or send access to it. For a mailbox to be useful for interprocess communication, other processes must be allowed to send messages. This function is used to grant all processes the ability to send messages to a mailbox created by the calling process. Note that all processes includes not only all currently created processes, but also any dynamic process which may be created in the future. The following routine illustrates the interface with the grantMailboxGlobalAccess( ) 56 function:
ipcStatus grantMailboxGlobalAccess (ipcMailboxHandle
handle);
Parameter Description
Handle Handle to the mailbox who access list is
to be changed.
Returned Status:
Status Description
IpcValid The specified access was granted to
the specified process.
IpcInvalidMailbox- The specified mailbox handle is not
Handle valid. It could have been modified by
the user inadvertently, or another
thread in the callers process could
have deleted the mailbox.
IpcInsufficient- The calling process is not the process
Privilege which created the mailbox. Only the
owner of a mailbox can change the
access rights.
Warnings/Restrictions: Only the process which owns a mailbox can change its access rights. Function: sendMessage( ) 58--This service is used to send a message to a specified mailbox. The following routine illustrates the interface to the sendmessage( ) 58 function:
ipcStatus sendMessage(
ipcMailboxHandle handle,
void *messageBuffer,
unsigned messageLengthInDwords,
bool blockIfMailboxFull);
Parameter Description
Handle Handle to the mailbox to send the
message to.
MessageBuffer Pointer to structure in caller
space containing the message to
send
MessageLengthInDwords Number of DWORDS to copy from
messageBuffer onto the envelope
(page needed to queue the message
in the mailbox)
BlockIfMailboxFull When false, and the destination
mailbox is full, the message will
not be sent and the
ipcQuotaExceeded will be
immediately returned.
When true, and the destination
mailbox is full, the calling thread
will be blocked until the message
can be queued. When a message is
received from a mailbox, a OS event
is pulsed which readies all the
blocked senders to the mailbox.
Exactly which blocked sender gets
to send its message is based on
priority. If multiple blocked
senders have the same priority, the
one which gets to send its message
is selected arbitrarily. Note that
multiple senders
can be located in multiple
processes, depending on how the
mailbox owner has granted access to
it.
Returned Status:
Status Description
IpcValid The message was send and queued in
the specified mailbox.
IpcInvalidMessage- When sending a message, an envelope
Length is created and the message is
copied onto the envelope. An
envelope is 4K, but sendMessage
uses the first 4 bytes as a message
length. MessageLengthInDwords
cannot exceed 4092 bytes.
ipcInvalid In order to send a message, an
envelope has to be created. In
this case, the envelope could not
be created. For more details on
why this could fail, refer to the
createEnvelope( ) primitive below.
IpcNoMessage The primitive sendEnvelope( ) failed
for some reason. Refer to it in the
primitives section below for
additional information.
IpcInsufficient- The calling process does has not
Privilege been granted access to the
specified mailbox.
Warnings/Restrictions: In order to send a message, the calling process must have a free envelope to send. When the sendmessage service complete, the envelope will be returned to the caller. When passing blockIfMailboxFull=true, be aware that the calling thread could be blocked for multiple periods and possibly forever. It will only resume when a message is received from the mailbox, and the mailbox owner could be another process. Note also that a higher priority sending process could re-fill the mailbox after a message has been received before the blocked sender gets to run, causing the blocked sender to remain blocked. Function: receiveMessage( ) 60--This service is used to receive a message from a mailbox. If there are multiple messages in the mailbox, the message that has been in the queue the longest is returned (i.e., its a FIFO queue). The following routine illustrates the interface to the receiveMessage( ) 60 function:
ipcStatus receiveMessage(
ipcMailboxHandle handle,
void *messageBuffer,
unsigned maxMessageSizeInDwords,
bool waitForMessage);
Parameter Description
Handle Handle to the mailbox to receive a
message from.
MessageBuffer Pointer to structure to store the
message in.
MaxMessageSize- When the message was sent, its length
InDWords was identified. By default, that many
unsigned words (4 bytes) will be copied
into messageBuffer. The service will
copy the proper number of unsigned
words (the number of bytes sent), but
will stop copying when maxMessageSize
words have been copied.
WaitForMessage When false, and the mailbox is empty
no message will be received and the
call will immediately return with the
ipcNoMessage status code.
When true, and the mailbox is empty,
the calling thread will be blocked
until a message is sent to the mailbox
and received by the thread. Note that
if there are multiple receiving threads
blocked on the mailbox, the message
will be given to the highest priority
thread. If there are multiple threads
of the same highest priority blocked on
the mailbox, the thread selection is
arbitrary.
Returned Status:
Status Description
IpcValid A message was obtained from the
mailbox and stored in messageBuffer.
IpcInvalidMail- The specified mailbox handle is
boxHandle invalid.
IpcInsufficient- The calling process is not the owner
Privilege of the mailbox.
IpcNoMessage There are no messages in the mailbox.
Warnings/Restrictions--The caller has no method of determining if the message was truncated when the message size exceeds maxMessageSize. The received message is simply truncated to maxMessageSize DWORDs. When passing waitForMessage=true, be aware that the calling thread could be blocked for multiple periods and possibly forever. It will only resume when a message is sent to the mailbox. Note also that a higher priority receiving process could receive the sent message before the blocked thread gets to run, causing the blocked receiver to remain blocked. Function: killMailbox( ) 62--This service is used to destroy a dynamic mailbox. Static mailboxes cannot be killed. When a mailbox is killed, the envelopes allocated to the mailbox are returned to the process' quota of envelopes. The time required to perform this service may vary, and is dependent on the number of sendMessage( ) 58 requests in progress, receiveMessage( ) 60 requests in process, getMailboxHandle( ) 52 requests in progress, etc. The killMailbox( ) 62 service will first mark the mailbox as invalid, preventing any new requests of it, but it allows any in progress services to complete before freeing up the resources. The following routine illustrates the interface to the killMailbox( ) 62 function:
ipcStatus killMailbox (ipcMailboxHandle handle);
Parameter Description
Handle Handle to the mailbox to delete.
Returned Status:
Status Description
IpcValid The mailbox has been destroyed.
IpcInvalidMailbox- The specified mailbox handle is
Handle invalid.
IpcInsufficient- The calling process is not the
Privilege process which created the mailbox
IpcCantDeleteStatic The specified mailbox is a static
mailbox and cannot be deleted.
Warnings/Restrictions: none
The aspects of the invention detailed below will allow those skilled in the art to implement any application through the operating system using an Ethernet interface. Specifically, the OS-specific characteristics of the socket interface are described.
Acronyms and Abbreviations
API Application Programmer
Interface
CPU Central Processing Unit
OS Operating System
IPC Inter-process Communication
NAP Network Application Process
FIG. 2 illustrates the elements of a network application 100 according to one embodiment of the invention. Typically, any process can be a Network Application Process (NAP). A NAP can communicate with external devices over an Ethernet interface. The NAP makes calls to functions in a socket library to communicate with one or more devices. As illustrated in FIG. 2, the elements of implementing a NAP include the network process 110, the socket library 120 and the user process 130. The network process 110 contains the device driver for the network hardware. The network process 110 is loaded onto the OS platform and included as a static process in the platform registry if network applications are to be used. The user is responsible for adding a static process based on the network process 110 template to the appropriate platform configuration using the OS Integration Tool. The socket library 120 is linked to the user process 130 and provides the interface to the network process 110. The process of accessing the network process 110 is illustrated in FIG. 3 and denoted generally as 150. Process 150 begins at step 152 when a thread in a user process 130 establishes a connection to the network process 100 by calling the init( ) function within the socket library 120. In response, at step 154 the network process 110 creates a thread to service the requesting thread in the user process. 130. As shown in steps 156 and 158, each thread in the user process 130 that calls init( ) causes another thread in the network process 110 to be created. This scheme provides an independent thread, step 158, in the network process 110 for each thread in the user process 130 that calls init( ). As a result, threads in the user process 130 can independently communicate with their corresponding external devices. A problem in accessing one device will not prevent other threads from accessing their devices. Preferably, the number of threads that can call init( ) may be changed by the user via the platform registry. FIG. 4 illustrates the process, denoted generally as 170, for writing a network application. Process 170 starts at step 172 wherein a process requiring network access calls the function startup( ) in the socket library 120. The socket library 120 can be provided with a mutex to support multi-threaded applications. Next, at step 174 threads requiring network access call the function init( ) in the socket library 120. The threads in the NAP should not use this mutex. A single call to init( ) is required by each thread that makes socket calls. The parameter specifies a dynamic thread template. The thread template refers to one of the dynamic threads that is defined for the network process 110. Their rates and budgets can be set according to the needs of the application. Next, at step 176, the corresponding threads in the network process 110 are started. Threads that called init( ) can call the function cleanup( ) when they no longer network access, step 178. If a dynamic process or thread is going to be deleted, cleanup( ) should be called prior to deletion. Each thread that calls init( ) should call cleanup( ). On the other hand, a thread that always makes socket calls does not have to call cleanup( ). The cleanup( ) function frees up resources in the network process 110. When init( ) is called, a thread is started in the network process 110 to service the thread that called the init( ) function. When the cleanup( function is called at step 178, the network process 110 deletes the thread that was created as a result of the call to init( ) at step 180, and makes the thread available for recreation if needed, step 182. A user process 130 that fails to call the cleanup( ) function could needlessly exhaust all resources of the network process 110 if that process is repeatedly created and deleted. In this case, all subsequent calls to init( ) by any user process 130 would fail, resulting in the network application being unable to perform network communications. In one embodiment, the socket library 120 communicates with the network process 110 using mailboxes. Whenever a socket call is made, a message is sent to the network process 110, which handles the request and sends back a response. Blocking mailboxes may be used for this purpose. Blocking mailboxes allow for control to be transferred between the user process 130 and the network process 110 more than once in a period. Therefore, more than one socket call can be completed in a period. Note that a thread that makes a socket call is "blocked" during the time that it waits for a response from the network process 110. This means it is not executing and is not using its budget of CPU time. When the response from the network process 130 is available, the thread is made running. Turning now to FIG. 5, the basic sequence used to make an API call is shown and denoted generally as 200. The sequence 200 begins when a user process 130 calls a function in the socket library 120. The call is indicated by the arrow 210. Next, the socket library 120 sends a message 212 to the network process 110 containing the information necessary for the network process 110 to fulfill the intent of the call 210. The network process 110 receives the message and performs whatever activity is necessary to fulfill the intent of the call 210. The network process 110 sends a message 214 to the user process 130 containing the return value to the call 210 and any related data. The socket library 120 receives the message on behalf of the user process 130. The socket library 120 returns 216 to the user process 130, providing the return value and data received from the network process 214. In one embodiment, before call 210 can be made, a function in the socket library 120 is called to establish access to the device driver software in the network process 110. This init( ) function may be called by each thread that requires access tp the network process 110. Access to the network interface uses resources in the network process 110 and thus it is desirable that a thread be able to free them up when they are no longer needed. This can be accomplished by a call to another function which is referred to as cleanup( ). By dynamically establishing and relinquishing access to the network interface, the use of dynamic threads and processes is supported by the present invention. A feature of the present invention is the one-to-one relationship between threads created by the user process 130 and those created in the network process 110. This relationship is illustrated in FIG. 6 and denoted generally as.225. By associating thread handles with mailbox handles, the user process 130 and the network process 110 create a communications link between a pair of threads. Thus, whenever Thread1 in the user process 130 makes a call 210, it will be handles by a corresponding Thread1 in the network process 110. This configuration does not limit the number of thread pairs that can be created. In addition, the number of processes that can establish a connection with the network process 110 is not limited since threads have independent access to the device driver software in the network process 110. In addition, Thread1 and Thread2 are able to communicate with different external devices independently. For example, if Thread1 attempts to receive data from its external device and the call 210 blocks, communications between Thread2 and its external devices are unaffected. In the prior art, this would not be the case since all threads are handled by a single thread in the network process. The process 250 for building a network application is illustrated in FIG. 7. Process 250 begins at step 252 when an application is linked with the socket library 120. The socket library 120 may be static (socket.lib) or dynamic (socket.dll), step 254. In the case of a static library, it is directly linked with the application, step 256. In the case of a dynamic library, the application is linked with an import library (socket.imp), step 258, and the DLL is loaded onto the platform, step 260. When the application is loaded onto the platform, it is linked with the DLL, step 262. Turning to FIG. 8, the process for configuring the OS platform is shown and denoted generally as 300. Process 300 starts at step 302 wherein the network process 110 is properly configured for successful network communications via registry. Configuring the network process 110 involves configuring each user process via the platform registry, step 304, for the network process 110 and all user processes 130. Next, the network process 110 is loaded onto the platform at step 306. In one embodiment, the platform registry entries provided below are the minimum required to support a user process 130. A particular user process 130 may need different entries depending on the resources it uses. Whatever the case, the user processes are loaded onto the platform, step 308, as well as the platform registry, step 310. Listed below are the registry entries for the user process 130 and the network process 110 along with the corresponding socket library references for the process 300 of configuring the OS platform according to one embodiment: Registry Entries for a User Process 130 Process template entries:
Mutexes 1
Dynamic Mailboxes One for each thread that calls
init( ).
Registry Entries for the Network Process 110 The network process 110 can be configured for the needs of the platform. Dynamic thread templates can be added, deleted or modified as needed. Process template entries:
Max Dynamic Threads The number of threads on the
platform that call init( ), and
can be expected
to be active simultaneously.
Max Dynamic Mailboxes One for each possible dynamic
thread.
The following entries may be applied to the threads that are created as a result of calling the function init( ). Socket Library Reference The socket library is based on an industry standard well known to those skilled in the art. int accept(int s, sockaddr *name, int *namelen) Return value:
Socket A value specifying
descriptor a valid socket.
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error, or no
connection requests were
pending on socket s.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be
called before calls to other
socket functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a message
to the Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
int bind(int s, const sockaddr *name, int namelen) Return value:
0 Success
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ).
It must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
int cleanup( ) Threads that call init( ) should call cleanup( ) when they no longer will be making socket calls. If a dynamic process or thread is going to be deleted, cleanup( ) should be called prior to deletion. Note that each thread that calls init( ) should call cleanup( ). If a thread is always going to make socket calls because it has no other purpose in life, cleanup( ) does not have to be called. This is a OS-specific function. Return value:
CLEANUP_STATUS.sub.-- The Network process was notified
SUCCESS that this thread will no longer
be making socket calls.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be called
before calls to other socket
functions (except startup( )).
int closesocket(int s) Return value:
0 Success
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be
called before calls to
other socket functions
(except startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
int connect(int s, const sockaddr *name, int namelen) Return value:
0 Success
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be
called before calls to
other socket functions
(except startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
hostentext *gethostbyname(char *name) Return value:
0 A null pointer is returned for
several error conditions: init( )
has not been called for this thread;
an error occurred in
attempting to send a message to the
Network process;
an error occurred in attempting to
receive a message from
the Network process; the call to the
Ethernet device driver
software (in the Network process)
encountered an error.
Valid pointer Success
int getlasterror( ) If one of the other functions returns SOCKET_ERROR, getlasterror( ) can be called to retrieve additional information about the error. This function returns the most recent error caused by the calling thread. Return value:
0 The calling thread has not caused an error.
Non-zero The error value associated with the most recent
value error caused by the calling thread.
int getpeername(int s, sockaddr *peer, int *addrlen) Return value:
0 Success
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be
called before calls to
other socket functions
(except startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
int getsockname(int s, sockaddr *name, int *namelen) Return value:
0 Success
SOCKET_ERROR The call to the Ethernet
device driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has not
NOT_CALLED called init( ). It must be
called before calls to
other socket functions
(except startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive a
message from the Network
process.
int getsockopt(int s, int level, int optname, char *optval, int *optlen) Return value:
SO_MAX_UDP_QUE Maximum number of input UDP packets which
will be queued on the socket at one time.
Any additional input packets will be
dropped. The default is no limit.
SO_NAGLE The Nagle Algorithm prohibits sending of
small TCP packets while there is an any
outstanding output data which has not been
acknowledged. The default is the Nagle
algorithm enabled.
SO_DELAY_ACK Delay sending TCP acknowledgment for up to
200 milliseconds. In a stream of full-size
packets, every other packet will be
acknowledged. The default is to delay the
acknowledgments.
SO_REUSESOCK Enable/disables ability to reuse a socket
in the timed-wait state if no other sockets
are available. The default is not to reuse
the socket.
SO_TCP_NO_COPY Enables/disables copying of TCP
input/output data directly to input/output
packets. The default is no copy mode
disabled.
SO_UDPCKSUN_IN Enables/disables checking input packet
checksums. The default is to check the
checksums.
SO_UDPCKSUM.sub.-- Enable/disables generating checksums for
OUT output packets. The default is to generate
checksums.
Return value:
0 Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
unsigned long htonl(unsigned long data) Return value:
Converted value for "data" Success
SOCKET_ERROR_INIT.sub.-- The calling thread
NOT_CALLED has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
unsigned short htons(unsigned short data) Return value:
Converted value for "data" Success
SOCKET_ERROR_INIT.sub.-- The calling thread
NOT_CALLED has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int init(DWORD threadSpecifier) A single call to init( ), which is a OS-specific function, is required by each thread that will be making socket calls. The parameter specifies a dynamic thread template. The threadtemplate refers to one of the dynamic threads that is defined for the network process. Return value:
INIT_STATUS_SUCCESS Successful
initialization.
INIT_STATUS.sub.-- The Network process
STRUCTURE_FULL and the socket
library use a data
structure to map
mailbox handles to
threads. This
structure can handle
up to 64 threads. An
attempt to start more
than 64 threads in
the Network process
results in this
return value.
INIT_STATUS_THREAD.sub.-- An attempt by the
NOT_CREATED Network process to
create a dynamic
thread from the
template specified by
threadSpecifier
failed. The template
ID must be consistent
with the platform
registry entries for
the Network process.
INIT_STATUS_NO.sub.-- An attempt to give
MAILBOX_ACCESS the Network process
access to the mailbox
created by this
process failed. This
could happen if the
Network process is
not loaded, or if the
name of the Network
process has been
changed without the
socket library being
rebuilt. In either
case, the call to
startup( ) would also
fail. This return
value also occurs if
the Network process
is unable to give
this process access
to its newly created
mailbox. This would
indicate a system
error or a problem
with the Network
process or socket
library. In this
case, startup( ) would
have succeeded.
INIT_STATUS_MAILBOX.sub.-- An attempt to create
NOT_CREATED a mailbox failed. The
attempt could have
been made by the
process calling
init( ), or by the
Network process. This
could be caused by an
insufficient quota of
mailboxes specified
in the platform
registry for the
Network process or
the process calling
init( ).
INIT_STATUS_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
INIT_STATUS_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
INIT_STATUS_ENVELOPE.sub.-- A mailbox envelope
CREATION_FAILED could not be created
by the socket
library.
int ioctlsocket(int s, int request, unsigned long *argp) return value:
0 Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int listen(int s, int backlog) Return value:
0 Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
unsigned long ntohs(unsigned long data) Return value:
Converted value for "data" Success
SOCKET_ERROR_INIT_NOT_CALLED The calling thread
has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE_NOT_SENT An error occurred in
attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE_NOT.sub.-- An error occurred in
RECEIVED attempting to receive
a message from the
Network process.
unsigned short ntohs(unsigned short data) Return value:
Converted value for "data" Success
SOCKET_ERROR_INIT.sub.-- The calling thread
NOT_CALLED has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int recv(int s, char *buf, int len, int flags) Return value:
Number of bytes received Success
SOCKET_ERROR The call to the
Ethernet device
driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread
NOT_CALLED has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR.sub.--MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int recvfrom(int s, char *buf, int len, int flags, sockaddr *from, int *fromlen) Return value:
Number of bytes received Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, timeval *timeout) Return value:
Number of ready sockets Success
0 Timeout
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int send(int s, char *buf, int len, int flags) int sendto(int s, char *buf, int len, int flags, sockaddr *to, int tolen) Return value:
Number of bytes sent Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR.sub.--MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int setsockopt(int s, int level, int optname, char *optval, int optlen) Return value:
0 Success
SOCKET_ERROR The call to the
Ethernet device
driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread
NOT_CALLED has not called
init( ). It must be
called before calls
to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the
Network process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int shutdown(int s, int how) Return value:
0 Success
SOCKET_ERROR The call to the
Ethernet device
driver software (in
the Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int socket(int domain, int type, int protocol) Return value:
Socket descriptor Success
SOCKET_ERROR The call to the
Ethernet device driver
software (in the
Network process)
encountered an error.
SOCKET_ERROR_INIT.sub.-- The calling thread has
NOT_CALLED not called init( ). It
must be called before
calls to other socket
functions (except
startup( )).
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_SENT attempting to send a
message to the Network
process.
SOCKET_ERROR_MESSAGE.sub.-- An error occurred in
NOT_RECEIVED attempting to receive
a message from the
Network process.
int startup (mutex_handle_t mutex) This is an OS-specific function to initialize communications with the network process 110. A single call to startup( ) is required by each network application process (NAP) before any other calls to the socket library. The socket library requires a mutex to support multi-threaded applications. Return value:
STARTUP_STATUS_SUCCESS Successful startup.
STARTUP_STATUS_NO.sub.-- The handle to the
MAILBOX_HANDLE Network process' static
mailbox could not be
obtained.
STARTUP_STATUS_NO.sub.-- The handle of the
PROCESS_HANDLE. Network process could
not be obtained.
While the invention has been described in conjunction with preferred embodiments, it should be understood that modifications will become apparent to those of ordinary skill in the art and that such modifications are intended to be included within the scope of the invention and the following claims.
|
Same subclass Same class Consider this |
||||||||||