From b8b63c33789640f4c7b1c5588413492c4ef73bf3 Mon Sep 17 00:00:00 2001 From: "dp%netscape.com" Date: Fri, 2 Apr 1999 21:43:54 +0000 Subject: [PATCH] progid spec added --- xpcom/doc/xpcom-code-faq.html | 158 ++++++++++++++------ xpcom/doc/xpcom-component-registration.html | 21 +-- 2 files changed, 126 insertions(+), 53 deletions(-) diff --git a/xpcom/doc/xpcom-code-faq.html b/xpcom/doc/xpcom-code-faq.html index 73ab921a1b50..d270c9cb363c 100644 --- a/xpcom/doc/xpcom-code-faq.html +++ b/xpcom/doc/xpcom-code-faq.html @@ -2,7 +2,7 @@ - + XPCOM Code FAQ @@ -11,25 +11,64 @@

XPCOM Code FAQ

Suresh Duddi <dp@netscape.com> -
Last Modified: March 22 1999 +
Last Modified: April 2 1999

I am documenting things randomly as I am replying to people's questions. -So this might look more like an FAQ. +So this looks more like an FAQ. +

+Table of Contents

+ +
    +
  1. +What are the +Global Objects that XPCOM maintains
    2. + +
  2. +What are the +static classes that XPCOM maintains
    3. + +
  3. +Is +there any restriction on which static class I should call first
    4. + +
  4. +What +is the order of creation of the ServiceManager, ComponentManager and Registry
    5. + +
  5. +Is there a global +Registry being maintained
    6. + +
  6. +ComponentManager +Vs ServiceManager
    7. + +
  7. +ProgID Vs CLSID
    8. + +
  8. +How to debug components ?
    9. +
+ +

-What are the Global Objects that XPCOM maintains

+What are +the Global Objects that XPCOM maintains

-What are the static classes that XPCOM maintains

+What are +the static classes that XPCOM maintains
nsComponentManager
nsServiceManager

-Is there any restriction on which static class I should call first

+Is +there any restriction on which static class I should call first
No restrictions. You can call any function from the static classes nsComponentManager and nsServiceManager. XPCOM will do the right @@ -40,8 +79,8 @@ it is only in Init_XPCOM() do we create register the RegistryFactory() with the ComponentManager.

-What is the order of creation of the ServiceManager, ComponentManager and -Registry

+What +is the order of creation of the ServiceManager, ComponentManager and Registry
Init_XPCOM()
@@ -67,7 +106,8 @@ from both NS_GetGlobalComponentManager() and NS_GetGlobalServiceManager() we will be safe.

-Is there a global Registry being maintained

+Is there a global +Registry being maintained
No. The nsIRegistry is designed to be lightweight access to the registry. Consumers who need to access the registry should use the @@ -79,7 +119,8 @@ is going to be a major headach.
 

-ComponentManager Vs ServiceManager

+ComponentManager +Vs ServiceManager
ComponentManager is the only way for component creation. ComponentManager always uses the component's factory @@ -95,36 +136,42 @@ to exist. Hence the notion of getting a service not creating one. (as opposed to the notion of Creating instances with the componentManager). ServiceManager is a convenience because components can technically force singletonism by making their factory return the same instance if one was created already. -The other big use of ServiceManager is the (still unimplemented) notion -of Shutting down a service. +The +other big use of ServiceManager is the (still unimplemented) notion of +Shutting down a service.

Client

  • When does a client use the service manager vs component manager
    • -


    When a client knows that the component that -they are trying to instantiate is a singleton, they need to call service -manager instead of component manager. Clients dont have to worry about -calling the ComponentManager at all in this case. The ServiceManager will -take care of creating the instance if the first one doesn't exist already. +
      +

      +

    When a client knows that the component that they +are trying to instantiate is a singleton, they need to call service manager +instead of component manager. Clients dont have to worry about calling +the ComponentManager at all in this case. The ServiceManager will take +care of creating the instance if the first one doesn't exist already.
    -

  • When does a client use the Component Manager as opposed to Service Manager
    • -


    When a client wants a private instance of -a component, they call the Component Manager. From the Clients point of -view, a new xpcom object creation happens everytime they call CreateInstance() -Anything else is an implementation detail that the Client need not worry -about. +
      +

      +

    When a client wants a private instance of a component, +they call the Component Manager. From the Clients point of view, a new +xpcom object creation happens everytime they call CreateInstance() Anything +else is an implementation detail that the Client need not worry about.
    -

  • How does a Client know that they have to instantiate a singleton
    • -


    For now, the Client just has to know. There -is no way of telling which component is a Service and which isn't. In fact, +
      +

      +

    For now, the Client just has to know. There is +no way of telling which component is a Service and which isn't. In fact, in todays xpcom (Mar 1999) any component can be accessed as a Service. Use your judgement until there is a proper method or service manager is eliminated. There is nothing even in the code that detects Services from @@ -138,7 +185,9 @@ dp@netscape.com

  • Can a component enforce use only as a Service
    • -


    No. The notion of the ServiceManager is available +
      +

      +

    No. The notion of the ServiceManager is available only to Clients.

    Note that at some points when a component wants another component, it actually behaves as a client and hence follows the @@ -164,26 +213,30 @@ the same object will be returned hence guaranteeing singletonism.

Should a component do anything at creation to become a Service -


No. Again, the notion of a ServiceManager -is available only to Clients. +
  +

  +

No. Again, the notion of a ServiceManager is available +only to Clients.
-

  • Can a component advertise that it is a service so clients can use it as one
    • -


    No. There isn't a way other than a comment in the interface of the -header file. +
      +

      +

    No. There isn't a way other than a comment in the interface of the header +file.

    -ProgID Vs CLSID

    +ProgID Vs CLSID
    ClassID or CLSID is the unique indentification of a component. It is a structure of huge numbers generated by using uuidgen on a windows box. It is represented as a string in documentation as {108d75a0-bab5-11d2-96c4-0060b0fb9956}

    ProgID is the string identification of an implementation of a component -the client is looking for. The representation takes a URI syntax. Eg. component://netscape/network/protocol&name=http -Some simplify this to, ProgID is a more readable string form of a CLSID. +the client is looking for. The representation takes a URI syntax. Eg. component://netscape/network/protocol?name=http;description=Http%20Protocol%20Handler +
    Some simplify this to, ProgID is a more readable string form of a CLSID. That is acceptable on the periphery. The ProgID is a Client thing. Components register with component manager to claim that they are the implementation for a ProgID. A component can register to be the implementation for multiple @@ -191,23 +244,42 @@ ProgIDs (not implemented yet).

    Client

    • -Should CreateInstance() calls use ProgID or CLSID
      -  
      -      ProgID is what Clients should use to CreateInstances. Clients should +Should CreateInstance() calls use ProgID or CLSID
      • + +


      ProgID is what Clients should use to CreateInstances. Clients should not even know about the CLSID unless they are hell bent on creating a particular -implementation of a component.
      -- -

    +implementation of a component. +
    - Component
    • -Should Components register with both a CID and ProgID
      -
      -      Absolutely.
      • -
    +Should Components register with both a CID and ProgID -
      +


    Absolutely. +

    + +

    +How to debug components ?

    + +
    Since components are dynamically loaded only on demand, debugging +them could be a hard. Here are some tips to debugging components. +

    Windows: VC5.0 VC6.0 +

      Include your component library in the Project->Settings, Additional +Dll. drop down. After that breakpoints can be enabled. +
       
    +Unix: gdb +
    Let the program run until you are sure that your component +is loaded. Type Control-C. Now all symbols from your component will be +available in gdb. Put your breakpoints and restart the app. Gdb will complain +that it cannot set the breakpoint, and that it is temporarily disabling +it, but when the *.so is loaded, the breakpoint is enabled automatically. +- <Eric Van Der Poel>
     
    +Mac: Codewarrior +
    Just open the appropriate .xSYM file in the debugger; the debugger +will target the library when the application is run. - <Simon +Fraser>
    +
    diff --git a/xpcom/doc/xpcom-component-registration.html b/xpcom/doc/xpcom-component-registration.html index 7b2a90cbf871..89658cdbdddc 100644 --- a/xpcom/doc/xpcom-component-registration.html +++ b/xpcom/doc/xpcom-component-registration.html @@ -151,7 +151,8 @@ do to salvage this situation other than warning the user of possible instability and advice a restart upon which the re-registration will happen.

    ProgID Spec

    -Let us consider some more examples: +The general format of ProgIDs is component://netscape/compname?var=value;var=value;var=value... +

    Let us consider some more examples:

    1. A pluggable protocol that implementes the nfs protocol
      2. @@ -176,31 +177,31 @@ they particularly do.

      The ProgID for these would look like

      1. -component://netscape/network-protocol&type=nfs
        2. +component://netscape/network-protocol?type=nfs
      2. -component://netscape/data-converter&type=application/x-zip
        3. +component://netscape/data-converter?type=application/x-zip
      3. -component://netscape/plugin&type=image/gif&name=ImageMedia's -Gif Image Plugin&Description=Reders GIF Images....
        4. +component://netscape/plugin?type=image/gif;name=ImageMedia Gif Image +Plugin;Description=Reders GIF Images....
      4. -component://netscape/widget&type=toolbar
        5. +component://netscape/widget?type=toolbar
      5. -component://netscape/rdf/datsource&type=mail
        6. +component://netscape/rdf/datsource?type=mail
      6. -component://netscape/helperapp&type=application/postscript
        7. +component://netscape/helperapp?type=application/postscript
      {Assume proper escaping of all above URI}

      The above semantics would let ProgID be an extensible mechanism that could be searched on multiple ways. And
      query on a progid should match only whatever was passed in. So a query for -
      component://netscape/plugin&type=image/gif should pass for the -progid specified above. We could extend this +
      component://netscape/plugin?type=image/gif should pass for the progid +specified above. We could extend this
      mechanism with wildcards, but I dont want to go there yet... :-)