Minor changes and documentation.
authorEmanuele Aliberti <ea@iol.it>
Wed, 23 Feb 2005 23:37:06 +0000 (23:37 +0000)
committerEmanuele Aliberti <ea@iol.it>
Wed, 23 Feb 2005 23:37:06 +0000 (23:37 +0000)
svn path=/trunk/; revision=13731

reactos/lib/smdll/compses.c
reactos/lib/smdll/connect.c
reactos/lib/smdll/execpgm.c
reactos/lib/smdll/readme.txt

index cc29d4e..eaaccbc 100644 (file)
 #include <sm/api.h>
 #include <sm/helper.h>
 
+#define NDEBUG
+#include <debug.h>
+
+/**********************************************************************
+ * NAME                                                        EXPORTED
+ *     SmCompleteSession/3
+ *
+ * DESCRIPTION
+ *     This function is called by an environment subsystem server to
+ *     tell the SM it finished initialization phase and is ready to
+ *     manage processes it registered for (SmConnectApiPort).
+ *
+ * ARGUMENTS
+ *     hSmApiPort: port handle returned by SmConnectApiPort;
+ *     hSbApiPort: call back API port of the subsystem (handle);
+ *     hApiPort  : API port of the subsystem (handle).
+ *
+ * RETURN VALUE
+ *     Success status as handed by the SM reply; otherwise a failure
+ *     status code.
+ */
 NTSTATUS STDCALL
-SmCompleteSession (HANDLE hSmApiPort, HANDLE hSbApiPort, HANDLE hApiPort)
+SmCompleteSession (IN HANDLE hSmApiPort,
+                  IN HANDLE hSbApiPort,
+                  IN HANDLE hApiPort)
 {
   NTSTATUS         Status;
   SM_PORT_MESSAGE  SmReqMsg;
     
+  DPRINT("SMDLL: %s called\n", __FUNCTION__);
+
   /* Marshal Ses in the LPC message */
   SmReqMsg.CompSes.hApiPort   = hApiPort;
   SmReqMsg.CompSes.hSbApiPort = hSbApiPort;
@@ -32,7 +57,7 @@ SmCompleteSession (HANDLE hSmApiPort, HANDLE hSbApiPort, HANDLE hApiPort)
   {
     return SmReqMsg.Status;
   }
-  DbgPrint ("%s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
+  DPRINT("SMDLL: %s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
   return Status;
 }
 
index 24fbca2..17ba96c 100644 (file)
@@ -11,6 +11,9 @@
 #include <sm/helper.h>
 #include <pe.h>
 
+#define NDEBUG
+#include <debug.h>
+
 /**********************************************************************
  * NAME                                                        EXPORTED
  *     SmConnectApiPort/4
@@ -44,16 +47,25 @@ SmConnectApiPort (IN      PUNICODE_STRING  pSbApiPortName  OPTIONAL,
   SM_CONNECT_DATA             ConnectData = {0,{0}};
   ULONG                       ConnectDataLength = 0;
 
+  DPRINT("SMDLL: %s called\n", __FUNCTION__);
+
+  if (pSbApiPortName->Length > (sizeof pSbApiPortName->Buffer[0] * SM_SB_NAME_MAX_LENGTH))
+  {
+         return STATUS_INVALID_PARAMETER_1;
+  }
   if (pSbApiPortName)
   {
     if (NULL == hSbApiPort || IMAGE_SUBSYSTEM_UNKNOWN == dwSubsystem)
     {
       return STATUS_INVALID_PARAMETER_MIX;
     }
+    RtlZeroMemory (& ConnectData, sizeof ConnectData);
     ConnectData.Subsystem = dwSubsystem;
-    memmove (& ConnectData.SbName, pSbApiPortName->Buffer, pSbApiPortName->Length);
+    RtlCopyMemory (& ConnectData.SbName,
+                  pSbApiPortName->Buffer,
+                  pSbApiPortName->Length);
   }
-  ConnectDataLength = sizeof (ConnectData);
+  ConnectDataLength = sizeof ConnectData;
 
   SecurityQos.Length              = sizeof (SecurityQos);
   SecurityQos.ImpersonationLevel  = SecurityIdentification;
@@ -76,7 +88,7 @@ SmConnectApiPort (IN      PUNICODE_STRING  pSbApiPortName  OPTIONAL,
   {
     return STATUS_SUCCESS;
   }
-  DbgPrint ("%s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
+  DPRINT("SMDLL: %s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
   return Status;
 }
 
index c0d67e5..4770968 100644 (file)
 #include <sm/helper.h>
 #include <string.h>
 
+#define NDEBUG
+#include <debug.h>
+
+/**********************************************************************
+ * NAME                                                        EXPORTED
+ *     SmExecuteProgram/2
+ *
+ * DESCRIPTION
+ *     This function is used to make the SM start an environment
+ *     subsystem server process.
+ *
+ * ARGUMENTS
+ *     hSmApiPort: port handle returned by SmConnectApiPort;
+ *     Pgm       : name of the subsystem (to be used by the SM to
+ *                 lookup the image name from the registry).
+ *                 Valid names are: DEBUG, WINDOWS, POSIX, OS2,
+ *                 and VMS.
+ *     
+ * RETURN VALUE
+ *     Success status as handed by the SM reply; otherwise a failure
+ *     status code.
+ */
 NTSTATUS STDCALL
-SmExecuteProgram (HANDLE hSmApiPort, PUNICODE_STRING Pgm)
+SmExecuteProgram (IN HANDLE          hSmApiPort,
+                 IN PUNICODE_STRING Pgm)
 {
   NTSTATUS         Status;
   SM_PORT_MESSAGE  SmReqMsg;
 
 
+  DPRINT("SMDLL: %s called\n", __FUNCTION__);
+
   /* Check Pgm's length */
   if (Pgm->Length > (sizeof (Pgm->Buffer[0]) * SM_EXEXPGM_MAX_LENGTH))
   {
@@ -26,7 +51,9 @@ SmExecuteProgram (HANDLE hSmApiPort, PUNICODE_STRING Pgm)
   /* Marshal Pgm in the LPC message */
   RtlZeroMemory (& SmReqMsg, sizeof SmReqMsg);
   SmReqMsg.ExecPgm.NameLength = Pgm->Length;
-  RtlCopyMemory (SmReqMsg.ExecPgm.Name, Pgm->Buffer, Pgm->Length);
+  RtlCopyMemory (SmReqMsg.ExecPgm.Name,
+                Pgm->Buffer,
+                Pgm->Length);
                
   /* SM API to invoke */
   SmReqMsg.ApiIndex = SM_API_EXECUTE_PROGRAMME;
@@ -42,7 +69,7 @@ SmExecuteProgram (HANDLE hSmApiPort, PUNICODE_STRING Pgm)
   {
     return SmReqMsg.Status;
   }
-  DbgPrint ("%s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
+  DPRINT("SMDLL: %s failed (Status=0x%08lx)\n", __FUNCTION__, Status);
   return Status;
 }
 
index af75bd8..6cfcfcc 100644 (file)
@@ -15,4 +15,29 @@ c) terminal emulators for optional subsystems, like posixw32 and os2w32,
 
 d) system and development utilites to debug/query the SM.
 
-2004-02-15 ea
\ No newline at end of file
+2004-02-15 ea
+
+
+How a subsystem uses these APIs
+===============================
+
+Thread #0                                                      Thread #1
+- create your own directory (\EXAMPLE)
+- create an event E0
+- create your call back API port (\EXAMPLE\SbApiPort)
+  and serving thread T1
+                                                               - wait connection requests on call
+                                                                 back port (\EXAMPLE\SbApiPort)
+- SmConnectApiPort(
+       \EXAMPLE\SbApiPort,
+       hSbApiPort,
+       SUBSYSTEM_ID,
+       & hSmApiPort)
+- wait for E0
+                                                               - as SM calls back, signal event E0
+- create your API port (\EXAMPLE\ApiPort) and
+  initialize the subsystem
+- call SmCompleteSession (hSmApiPort,
+                         hSbApiPort,
+                         hApiPort)
+- manage processes etc.
\ No newline at end of file