Hello there folks!

I'm pretty new to the topic of C3PO, GW and all the Novell stuff and one of my tasks was to "code an export mechanism for GW8 thats lats us save e-mails to our storage system". Ok, that was a hammer. But wrapping my head around it and starting to error out the things got me pretty far and I guessed it was tutorial material. So here we go:

@Moderators: This is the thread that has everything in it. the other one can be deleted.

This tutorial is intendend for C# only. I don't like VB and I'm too dumb for C++ so if you need it for another dialect you need to work it out your self.

Agenda:
  1. Needed packages
  2. C3PO wizard
  3. Loading to Visual Studio 2010
  4. Needed Imports/References
  5. Simple MessageBoxing
  6. Export Code
  7. Registering and caching the .DLL
  8. Testing (please help me with a better way here)



1. Needed packages
  • the novell-gwc3po-devel-2012.11.15.zip file (unzip this after downloading)
  • an installed version of Visual Studio 2012 C# (or if you want to work with a different dialect choose another)
  • cmd access to some of the registering tools:
    It may be the best thing to set tose paths up in you env variables. Allthough when running the cmd with administrator privileges you can't use regasm from env variables and need to cd to the directory.
    • RegAsm (regasm.exe): C:\Windows\Microsoft.NET\Framework\v4.0.30319 (the version depends on the target)
    • GACUtil (gacutil.exe): C:\Program Files(x86)\Micrsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\ (this path is also dependent on your target framework version, I chose .NET4)
    • StrongName (sn.exe): C:\Program Files(x86)\Micrsoft SDKs\Windows\v7.0A\Bin\NETFX 4.0 Tools\ (this path is also dependent on your target framework version, I chose .NET4)
  • a good beverage :D (you should obtain multiple of these :D)



2. The C3PO wizard
In my case I wanted to add the functionality via the context menu. So the code executes when right-clicking on one or multiple messages displays another menu item and is clickable.

This is pretty easy to realize via the C3PO wizard. You'll find it in the downloaded and extracted novell-gwc3po-devel-2012.11.15.zip from above. Start it (it is located in extracted-zip-folder/gwc3po-FILES/C3POWizard/C3POWizard.exe) and setup your project:
Setup the project in the wizard step 1
I usually setup the Wizard inside my Visual Studio 2010 projects folder, create a new folder there with the name of the project and check the options i want to have.

In the next step I chose which type of View should display my custom context menu. Since I was only interested in exporting and working with e-mails I chose "GW.MESSAGE.MAIL" and added it to the bottom list via, you guessed it, "Add".
Setup theView that invokes the new context menu item

In the next step you I had to setup a new entry for the context menu. You could make side-droppable menus here etc. But for me a simple "Add Menu" was enough. Give it a name of your choice (beware: I'm yet to find out where to change this setting in the source files).
Creating a Menu Item in step 3

Click through next and the wizard will sum up you choices. In the next dialog window you will be prompted to specify the language you want the code to be generated. I chose .NET C#.
In the prompt after that you will be asked if the wizard should create a .DLL-project. You click yes.
Quit the wizard with the "Done" button.

3. Loading to Visual Studio 2010
Open up your Visual Studio and go to File -> Open Project. Navigate to the folder where you just created the files with the C3PO-Wizard. and open up the .csproj file.

All the files get loaded and it seems quite well. but now it's time for some other stuff: Signing, or better, providing a key for signing.

Allthough the README.txt (also in your project folder) states this is not neccessarily needed I did not get it to work without a key file.
Open up a terminal and tpye in sn /? to see if the environment variables work. If not you can yuse the abolute path to sn (see: 1: Needed packages). If everything works as expected you can generate your keyfile with sn -k <PathToYourProject>\Archive.snk.

In Visual Studio, go to Project -> <ProjectName>-Properties -> Signing -> Sign assembly [x] -> Search and pick the .snk-file you just created.

Good. A first compilation of the project with F6 should rumble through without problems. Go to <ProjectFolder>\bin\Release and copy the .dll files to <GroupWiseInstallPath>.

After that you need to open a cmd windows as administrator and cd to the RegAsm.exe directory and execute the following: [I]regasm "<GroupWiseInstallPath>\<TheDllName>.dll". Then execute gacutil -i "<GroupWiseInstallPath>\<TheDllName>.dll".

RegAsm will register the extension to the Windows registry and GACUtil will cache the .dll content to make it available to GroupWise.

You need to re-cache the .dll everytime you compile in VS. So basically the workflow is Compile -> Copy dll to GroupWise directory -> re-cache with gacutil -i -> Start Groupwise

I have not found a method to post-build execute a script that does that. Problem is the copying and the gacutil caching (both must be done as administrator).

IIf everything worked you see a new entry in the context menu when right-clicking a mail in Groupwise. When you click it, there will appear a message box.

The MessageBox is defined in GWCommand.cs L. ~125

4. Needed Imports/References
Since we got the skeleton to compile and function properly, it's time to get our own code in there. FOr rapid prototyping I do all the stuff in GWCommand.cs.

Go to Project -> add Reference -> COM and select "C3POTypeLibrary", "GroupWareTypeLibrary, "GroupWiseCommander", "GroupWiseConnectorLibrary" and click OK. The selected entries now appear in the project explorer.

5. Simple MessageBoxing
A thing I like to do (because I'm not a very good programmer) is to get all sorts of infos to get displayed with
Code:
MessageBox.Show();
.

Just fling it in the code and see what get's where etc. An important thing is allready in the comments of the file.
It is this line:
Code:
 C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;
. Uncomment it and play around with the myCL-object in your code.

The myCL has some properties we will use later on such as myCL.SelectedMessages which is exactly what we need for our archive functionality.

6. Export Code
Now we get to the code:

With the
Code:
ClientState
dug up in the code we can pass the
Code:
SelectedMessages
into a
Code:
MessageList
. Over this MessageList we will iterate and save each
Code:
Message
with the so called
Code:
GroupWiseCommander
to our disk. well that sounds simple. And, well after digging through a lot of threads here on the forum and the documentation, it is.

Here is the Execute() method from GWCommand.cs:
It has comments that should serve as a documentation.
Code:
public void Execute()
        {
            try
            {
                switch (m_PersistentID)
                {
                    case WIASSArchivButton.vWIASS:
                        //C3PO WIZARD Put execute command code here for WIASS Context menu.


                        /* this was in the comments and is essential! 
                         * the myCL object provides us everything we need to interact with the messages */
                        C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;

                        // get the selected messages
                        object o = myCL.SelectedMessages;
                        // and convert the SelectedMessages to a MessagesList
                        MessageList ml = (MessageList)o;

                        // iterate over all the selected Messages
                        // this was tricky: the index of the MessageList starts by 1 and not at 0
                        for (int i = 1; i <= ml.Count; i++)
                        {
                            // the .Item() method expects either a string or a long
                            // see http://www.novell.com/documentation/developer/groupwise_sdk/gwsdk_gwobjapi/data/h20s5bdo.html
                            long index = (long)i;

                            // instantiate a Message object to get access to the different properties like subject, sender etc
                            GroupwareTypeLibrary.Message oMessage = (GroupwareTypeLibrary.Message)ml.Item(index);

                            // instantiate a GroupWiseCommander
                            // this is the interface to the TOKEN API
                            // TOKENS: https://www.novell.com/developer/documentation/gwtoken/index.html
                            GroupWiseCommander.GWCommander cmdr = new GroupWiseCommander.GWCommander();

                            // the GWCommander has an Execute() method that is able to take certain tokens kind of like SQL
                            // lets build the token (the complete list is huge and awesome) to save our Messages
                            // ItemSaveMessage(): https://www.novell.com/developer/documentation/gwtoken/gwtokens/data/hbt0bd7x.html
                            string tokenCommand = "ItemSaveMessage(\"" + oMessage.MessageID + "\"; \"C:\\archiv\\" + oMessage.MessageID + ".eml\"; 900)";

                            /* what happens here ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ is that we build us a TOKEN command that the 
                             * GWCommander is able to execute.
                             * the actual command is ItemSaveMassge()
                             * everything between the semi-colons are the parameters:
                             *        \"" + oMessage.MessageID + "\" : builds an ANSISTRING of the MessageID which we get from the oMessage onject
                             *        \"C:\\archiv\\" + oMessage.MessageID + ".eml\" : build an ANSISTRING  of the output filename
                             *        900 is the type we want to export. 900 stands for Mime
                             *
                             *        CAUTION:In this example I use C:\archive\ as the destination folder. It must exist and be writable to the program
                             */
                            

                            // now that we have setup our command we can get it executed by the commander
                            // the result is sort of a callback variable
                            string result ="";
                            cmdr.Execute(tokenCommand, out result);

                            /* here can the error handling be done with the result string
                        }
                       
                        break;

                    default:
                        MessageBox.Show("Unsupported Case", "Error", MessageBoxButtons.OK);
                        break;
                }

                //A way to get the GroupWise client state with newest interface
                //C3POTypeLibrary.IGWClientState6 myCL = (C3POTypeLibrary.IGWClientState6)WIASSArchivButton.g_C3POManager.ClientState;

                //uncomment the code below to unblock the base command
                //IGWCommand baseCmd = (IGWCommand)WIASSArchivButton.g_C3POManager.CreateGWCommand(m_objBaseCmd);
                //baseCmd.Execute();
            }
            catch (Exception e)
            {
                MessageBox.Show("Error Executing GWCommand: " + m_PersistentID.ToString() + " Error: " + e.Message);
           }

           return;
        }
7. Registering and caching the .DLL
After that you need to open a cmd windows as administrator and cd to the RegAsm.exe directory and execute the following: regasm "<GroupWiseInstallPath>\<TheDllName>.dll". Then execute gacutil -i "<GroupWiseInstallPath>\<TheDllName>.dll".

RegAsm will register the extension to the Windows registry and GACUtil will cache the .dll content to make it available to GroupWise.

You need to re-cache the .dll everytime you compile in VS. So basically the workflow is Compile -> Copy dll to GroupWise directory -> re-cache with gacutil -i -> Start Groupwise

8. Testing (please help me with a better way here)
Is there a good way to hook every thing up together to jsut stay in VS , compile, files get copied, registered, cached and GW starts?

Thanks for reading!

I wrote this up to have a documentation for myself and others. please let em know if you need help or anything is missing or not clear. It's certainly not a total noob guide and I expect a bit of knowledge to be honest.

Regards
Sebastian