My public notepad

Thread and process synchronisation with mutex

2012-01-30T17:20:00.000Z

In my previous article I described how to use semaphore in order to synchronise threads or processes. Mutex is a semaphore specialisation and can be used in the special case - when only one thread (or process) is allowed to access shared resource.

Mutex is a synchronisation object that controls resource access (critical section execution) by maintaining the knowledge of its current owner (accessor - thread or process). Mutex strictly limits access to a single accessor at a time.

Ownership over the mutex is controlled with following operations:

acquire() (or lock()) - passes the ownership of the mutex to the calling thread
release() (or unlock()) - calling thread gives up its ownership of mutex. Only thread that acquired the mutex can release it

Mutex has two states:

signalled - when no thread owns it; acquire() does not block
non-signalled - when owned by some thread; acquire() in other thread blocks till mutex gets signalled

When Thread1 acquires ownership of mutex, it has a exclusive right to access the shared resource (to execute the code in the critical section). Once it's finished, it needs to release mutex so another thread can acquire ownership and access the resource. If thread does not release the mutex, other threads cannot acquire it and application is in a deadlock. It is therefore very important to make sure that mutex is released under any condition, no matter of the outcome of the code in the critical section! RAII-compliant design can prevent program's execution to leave critical section's scope without releasing the mutex.

Semaphore behaves like shared mutex with a count controlled by multiple threads that are allowed to access shared resource. Mutex is stricter, only thread that owns it has the power to release it, and only that thread can access shared resource.

The following example shows how to use mutex in order to synchronise processes that write into the shared file (problem described in this article):

main.cpp:

Links and References:

Mutex Objects (MSDN)
Using Mutex Objects (MSDN)
Mutual exclusion (Wikipedia)

Thread and process synchronisation with semaphores

2012-01-30T14:25:00.000Z

Semaphore is a synchronisation object that controls resource access (critical section execution) by maintaining the number (count, n) of accessors (threads or processes) (still) allowed to access the resource. While mutex strictly limits access to a single accessor at a time, semaphore allows up to N (N > 0) parallel accessors. N is defined when semaphore is being created and it represents maximum possible value of the semaphore count.

Semaphore count is changed through following operations:

wait() - which, on return, decreases count on successful return (minimum is 0)
release() - which increases count (maximum is N)

Semaphore has two states:

signalled - when 0 < n <= N; wait() does not block
non-signalled - when n == 0; wait() blocks till semaphore gets signalled (or returns on expired timeout)

There are two types of semaphores:

counting - based on the count 0 <= n <= N where N > 1
binary - (specialisation of counting) where N == 1; when in signalled state we say it is unlocked; when in non-signalled state we say it is locked

Semaphores are signalling accessors the right of way - just as traffic semaphores, but unlike them, accessors themselves are controlling when the light for others will become green - through wait() and release() operations. Accessors are wait()-ing for a semaphore. If semaphore is signalled (n > 0), wait() returns immediately, decreasing semaphore count. When accessor (this one or any other) is finished with the shared resource it calls release() on the semaphore, increasing its count. Accessor will block on wait()-ing if semaphore is non-signalled (when maximum allowed number of accessors are sharing the resource). As soon as some accessor finishes the work and releases the semaphore, accessor's wait() will unblock and it will be allowed to access the resource.

Obviously, if N is set to 1, semaphore (called binary semaphore in this case) logically behaves like a mutex, allowing only one accessor at a time. There is a difference between two of them though: only accessor that locked the mutex can unlock it (mutex is owned by the accessor), but any accessor can release semaphore.

Majority of semaphore examples on the internet are focused on consumer-producer problem. I wanted to show use of semaphore on the example of traffic control - something that resembles the real semaphore. So, let's say we have three single-lane, one way roads joining just before a bridge which is one way but has two lanes. To reduce congestion on the bridge, traffic from only two access roads is allowed at a time. There is a semaphore with the red and green light by the each road and once it turns green, it remains in that state for some time period T. First two opened roads get green light first. As soon as the timeout expires for one of those roads and semaphore shows red, semaphore will show green for traffic that has been waiting at the third road.

We can think of roads (traffic on them) as accessors and the bridge as a resource: two roads can lead traffic to the bridge at the same time (two accessors are allowed to access shared resource). Obviously, we will set the maximum value for the semaphore count to 2 in our model. Thread will wait() as long as count is 0 but as soon as it gets increased to 1, wait() returns (decreasing count to 0 again).

This example aims to show how semaphore limits parallel access to the shared resource and how accessors (threads in this case) themselves control semaphore by wait()-ing for the semaphore and release()-ing it.

To stop threads I tend to use event object - not a flag (volatile bool variable). They are thread-safe and thread callbacks don't need to return with delay of one additional wait() cycle in the case when termination has been requested.

I wrapped event and semaphore objects (handles) into RAII-compliant classes - CScopedEvent and CScopedSemaphore.

main.cpp:

Output:

Road 1 opened
0 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
1 road(s) is(are) generating traffic...
Road 2 opened
1 road(s) is(are) generating traffic...
Road 2 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...
Road 3 opened
2 road(s) is(are) generating traffic...

Road 1 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 3 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 2 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 3 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 2 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 1 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 3 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 2 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 3 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 2 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 1 got red light. Waiting for a green light...
Road 3 got green light for the next 10 seconds. Generating traffic...
1 road(s) is(are) generating traffic...2 road(s) is(are) generating traffic...

Road 2 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 3 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 2 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 1 got red light. Waiting for a green light...
Road 3 got green light for the next 10 seconds. Generating traffic...
1 road(s) is(are) generating traffic...
2 road(s) is(are) generating traffic...

Road 2 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 3 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 2 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...
Closing road 3 ...
Road 3 got request to get closed
Road 3 closed
Closing road 2 ...

Road 1 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 1 got green light for the next 10 seconds. Generating traffic...
2 road(s) is(are) generating traffic...

Road 2 got red light. Waiting for a green light...
1 road(s) is(are) generating traffic...
Road 2 got request to get closed
Road 2 closed
Closing road 1 ...

Road 1 got red light. Waiting for a green light...
0 road(s) is(are) generating traffic...
Road 1 got request to get closed
Road 1 closed

The example above shows how semaphore controls access to the resource by multiple threads. But please note that resource was NOT made thread safe! Semaphore was just allowing up to N threads (2 in our case) to be active at a time (and generate the traffic towards the bridge). If we wanted to limit the number of vehicles on the bridge and to control traffic lights depending on the current bridge load, we would have had to limit the number of active threads to 1. In that case only one road would have green light at a time.

In the next example I want to show how to synchronise multiple processes in accessing shared resource. Let's say we have an app which writes some log into the file and does it in a loop. The code could look like this:

main.cpp:

If run with parameter of value e.g. "012345", this app will create text file with the following content:

test.log:

[PID = 4408] Iteration # 1 012345
[PID = 4408] Iteration # 2 012345
[PID = 4408] Iteration # 3 012345
[PID = 4408] Iteration # 4 012345
...

If we run simultaneously two or more instances of this process, they will all write into the same file, increasing its size with each write operation. Manipulator endl inserts new line character ('\n') at the end of the line and flushes the buffer to the disk. Obviously, before writing to the disk, our file stream object needs to know the current size of the file in order to move write pointer to the file end. If Process2 appends a new line to the file after Process1 reads file size but before Process1 writes into it, Process2 will increase file size but Process1 will know only about the previous file size and start writing at the position set accordingly, effectively overwriting Process2's last written line!

The following code is the content of the script (DOS batch file) which runs three instances of our application, providing each with different argument:

run_processes.bat:

@start Process.exe 012345
@start Process.exe ABCDEFHIJKLM
@start Process.exe 987654321

Arguments are of different length so we can easily detect the place of the corruption in the output file, like this one:

test.log:

...
[PID = 8280] Iteration # 214 ABCDEFHIJKLM
[PID = 8120] Iteration # 208 987654321
M
[PID = 8280] Iteration # 216 ABCDEFHIJKLM
...

What happened here? First of all, we need to know that on Windows, \n read from stream buffer is expanded to \r\n (CR-LF) before writing it to the file on disk. Process 8120 has updated its knowledge of file size but before it wrote iteration #208 log, process 8280 had written its log for iteration #215 so basically we had this:

test.log (showing hidden CR-LF characters):

...
[PID = 8280] Iteration # 214 ABCDEFHIJKLM\r\n
[PID = 8280] Iteration # 215 ABCDEFHIJKLM\r\n
...

Then process 8120 wrote its #208 log, but effectively overwriting 8280's #215, after what 8280 wrote its log #216:

test.log (showing hidden CR-LF characters):

...
[PID = 8280] Iteration # 214 ABCDEFHIJKLM\r\n
[PID = 8120] Iteration # 208 987654321\r\nM\r\n
[PID = 8280] Iteration # 216 ABCDEFHIJKLM\r\n
...

Obviosuly, we need to protect file so only one process is accessing it at a time. We can do that with semaphore or mutex which are shared between multiple processes (and therefore must be named).

In this article I will show how to achieve it with semaphore:

main.cpp:

All processes are competing to get semaphore signal. First process whose wait() returns (decreasing semaphore count by 1 - possibly to minimal value of 0 in which case all other processes block on their wait()) gets a exclusive access to a file and updates its content after which it releases semaphore (increasing its count to 1 again). All processes are competing again and the one whose wait() returns first gets its slot of exclusive access. There is no corruption in the file any more:

test.log:

...
[PID = 6036] Iteration # 213 987654321
[PID = 10940] Iteration # 213 012345
[PID = 11644] Iteration # 213 ABCDEFHIJKLM
[PID = 6036] Iteration # 214 987654321
[PID = 10940] Iteration # 214 012345
[PID = 11644] Iteration # 214 ABCDEFHIJKLM
[PID = 6036] Iteration # 215 987654321
[PID = 10940] Iteration # 215 012345
[PID = 11644] Iteration # 215 ABCDEFHIJKLM
...

Note: Although this example uses semaphore for process synchronisation, mutex is here more natural solution - we don't want to limit number of accessors to several (N) but only to 1. Only process that locks the mutex can unlock it and with binary semaphore we are just emulating this behaviour.

Links and References:
Semaphore Objects (MSDN)
Using Semaphore Objects (MSDN)
Semaphore (Wikipedia)
Windows Thread Synchronization - Synchronization Using Semaphores
Joseph M. Newcomer: Semaphores
Mutex or Semaphore for Performance?
Mutex vs Semaphore

Mutex vs Semaphores
Difference between binary semaphore and mutex

UML Class Diagrams and Class Relationships

2012-01-19T15:14:00.000Z

UML Class Diagrams display relationships between classes in a given model. Here is a list of various types of class relationships and statements that can describe them:

generalization ("A is a kind of B")
realization ("A implements B")
dependency ("A uses B and forgets about it", "A can send message to B")
association ("A uses B and keeps it", "A has B")
aggregation ("B can be a part of A (whole)", "B can outlive A", "B can be shared between many As")
composition ("B is a part of A (whole)", "A owns B", "B cannot outlive A", "B belongs only to one A")

It is usually easy to distinguish generalization from realization, aggregation from composition but the border line between dependency, association and aggregation is a bit blurry. All these relationships are actually some kinds of associations which differ in subtle details and which can be redefined depending on the context. Different books and articles on UML sometimes define these relationships in a very different way ("dependency is a type of association" vs. "association is a type of dependency", "aggregation is meaningless"...) and some are even advising (with a reason!) to give up differentiating them:

"Rule 145. Don't Worry About the Diamonds: When you are deciding whether to use aggregation or composition over association, Craig Larman (2002) says it best: "If in doubt, leave it out." The reality is that many modelers will agonize over when to use aggregation when the reality is that there is very little difference between association, aggregation, and composition at the coding level." [12]

I tried to find an algorithm which goes through a set of questions (based on aforementioned statements) about the relationship between class A and class B and which at the end yields the name of that relationship.

Here is the algorithm I came up with:

Here are some descriptions of class relationships I found in various UML-related books:

Dependency

The weakest relationship between classes is a dependency relationship. Dependency between classes means that one class uses, or has knowledge of, another class. It is typically a transient relationship, meaning a dependent class briefly interacts with the target class but typically doesn't retain a relationship with it for any real length of time. Dependencies are typically read as "...uses a...". For example, if you have a class named Window that sends out a class named WindowClosingEvent when it is about to be closed, you would say "Window uses a WindowClosingEvent." You show a dependency between classes using a dashed line with an arrow pointing from the dependent class to the class that is used. [1]

A dependency exists between two elements if changes to the definition of one element (the supplier) may cause changes to the other (the client). With classes, dependencies exist for various reasons: One class sends a message to another; one class has another as part of its data; one class mentions another as a parameter to an operation. If a class changes its interface, any message sent to that class may no longer be valid. (...) The UML allows you to depict dependencies between all sorts of elements. You use dependencies whenever you want to show how changes in one element might alter other elements. [2]

(...) Your general rule should be to minimize dependencies [2]

(... ) The most common case I use for dependencies with classes is when illustrating a transient relationship, such as when one object is passed to another as a parameter. [2]

...one class uses another. This is called a dependency. The most common usage of a dependency is to show that the signature of one class' operation uses another class. [3]

Dependency—the relationship between a component and an interface through which it accesses another component. (...) dependency is visualized as a dashed line with an arrowhead. [3]

You model interaction through an interface as a dependency. [3]

Sometimes the relationship between a two classes is very weak. They are not implemented with member variables at all. Rather they might be implemented as member function arguments. (...) This is the dependency relationship. In Booch94 this was called a ‘using’ relationship. This relationship simply means that A somehow depends upon B. In C++ this almost always results in a #include. [5]

A dependency is a "using" relationship within which a change in one thing (such as a class) may affect another thing (for instance, another class). The dependent element is called the client or source; the independent element is called the supplier or target. A dependency involving two classes appears as a dashed line with a feathered arrow pointing at the supplier. [8]

The UML includes a general dependency relationship, which indicates that one element (of any kind, including classes, use cases, and so on) has knowledge of another element. It is illustrated with a dashed arrow line. In class diagrams the dependency relationship is useful to depict non-attribute visibility between classes; in other words, parameter, global, or locally declared visibility. By contrast, plain attribute visibility is shown with a regular association line and a navigability arrow. For example, the Register software object receives a return object of type ProductSpecification from the specification message it sent to a ProductCatalog. Thus Register has a short-term locally declared visibility to ProductSpecifications. And Sale receives a ProductSpecification as a parameter in the makeLineItem message; it has parameter visibility to one. These non-attribute visibilities may be illustrated with the dashed arrow line indicating a dependency relationship. [9]

Dependency relationships are indicating non-attribute visibility. [9]

Association

Associations are stronger than dependencies and typically indicate that one class retains a relationship to another class over an extended period of time. The lifelines of two objects linked by associations are probably not tied together (meaning one can be destroyed without necessarily destroying the other). Associations are typically read as "...has a...". For example, if you have a class named Window that has a reference to the current mouse cursor, you would say "Window has a Cursor". Note that there is a fine line between "...has a..." and "...owns a..." (see "Aggregation" later in this section). In this case, Window doesn't own the Cursor; Cursor is shared between all applications in the system. However, Window has a reference to it so that the Window can hide it, change its shape, etc. You show an association using a solid line between the classes participating in the relationship.[1]

The other way to notate a property is as an association. Much of the same information that you can show on an attribute appears on an association. [2]

An association is a solid line between two classes, directed from the source class to the target class. The name of the property goes at the target end of the association, together with its multiplicity. The target end of the association links to the class that is the type of the property. [2]

As an alternative to labeling an association by a property, many people, particularly if they have a data-modeling background, like to label an association by using a verb phrase so that the relationship can be used in a sentence. This is legal and you can add an arrow to the association to avoid ambiguity. Most object modelers prefer to use a property name, as that corresponds better to responsibilities and operations. [2]

(...) Because you don't need an association to a class to send a message to it, you may also need to add a dependency arrow to show messages between classes that aren't associated. [2]

When classes are connected together conceptually, that connection is called an association. [3]

When one class associates with another, each one usually plays a role within that association. You can show each class’s role by writing it near the line next to the class. In the association between a player and a team, if the team is professional, it’s an employer and the player is an employee [3]

An association declares that there can be links between instances of the associated types. It has at least two ends represented by properties, each of which is connected to the type of the end. An association declares that there can be links between instances of the associated types. [4]

There are other forms of containment that do not have whole / part implications. For example, Each Window refers back to its parent Frame. This is not aggregation since it is not reasonable to consider a parent Frame to be part of a child Window. We use the association relationship to depict this. (...) An association is nothing but a line drawn between the participating classes. (...) Once again note the name on the role. This relationship will almost certainly be implemented with a pointer of some kind. [5]

What is the difference between an aggregation and an association? The difference is one of implication. Aggregation denotes whole/part relationships whereas associations do not. However, there is not likely to be much difference in the way that the two relationships are implemented. That is, it would be very difficult to look at the code and determine whether a particular relationship ought to be aggregation or association. For this reason, it is pretty safe to ignore the aggregation relationship altogether. As the amigos said in the UML 0.8 document: “...if you don’t understand [aggregation] don’t use it.” [5]

Aggregation and Association both correspond to the Has-by-reference relationship from the Booch-94 notation. [5]

There are other types of relationships that do not fit neatly into a generalization (a-kind-of) or aggregation (a-part-of) framework. Technically speaking, these relationships are usually a weaker form of the aggregation relationship. For example, a patient schedules an appointment. It could be argued that a patient is a-part-of an appointment. However, there is a clear semantic difference between this type of relationship and one that models the relationship between doors and cars or even workers and unions. As such, they are simply considered to be associations between instances of classes. [6]

Association: Objects of one class are associated with objects of another class. [7]

Association is a weak form of connection: the objects may be part of a group, or family, of objects but they’re not completely dependent on each other. For example, consider a car, a driver, a passenger and another passenger. When the driver and the two passengers are in the car, they’re associated: they all go in the same direction, they occupy the same volume in space, and so on. But the association is loose: the driver can drop off one of the passengers to go their separate way, so that the passenger is no longer associated with the other objects. [7]

According to the UML standard, all run-time relationships come under the umbrella term association. However, most people use the term ‘association’ to mean ‘an association that isn’t aggregation or composition’. Choosing between relationships can be tricky – you need to use intuition, experience and guesswork. During analysis, you should expect the frequency of these kinds of relationship to be: association > aggregation > inheritance > composition. As far as design and implementation are concerned, the differences between association, aggregation and composition can be difficult to spot. [7]

All relationships, except inheritance, can be given an association label, indicating the nature of the association. If it’s not obvious which way the association name should be read, a black arrowhead can be used. [7]

As well as association names, we can show roles. A role indicates the part played by an object in the association – the role is shown as a label near the object that plays the role. [7]

An association is a relationship between types (or more specifically, instances of those types) that indicates some meaningful and interesting connection. [9]

In the UML associations are defined as "the semantic relationship between two or more classifiers that involve connections among their instances." [9]

Associations worth noting usually imply knowledge of a relationship that needs to be preserved for some duration — it could be milliseconds or years, depending on context. In other words, between what objects do we need to have some memory of a relationship? (...) Associations for which knowledge of the relationship needs to be preserved for some duration ("need-to-know" associations). [9]

Focus on those associations for which knowledge of the relationship needs to be preserved for some duration ("need-to-know" associations). [9]

We should add those associations which the requirements (for example, use cases) suggest or imply a need to remember, or which otherwise are strongly suggested in our perception of the problem domain. [9]

An attribute is related to an association [9]

How to Discover Associations: During system use-case interviews, look out for statements of the form X [verb] Y, where X and Y represent business objects. They often reveal associations. For example, in “A Peace Committee supervises a Case,” Peace Committee is associated with Case; the association name is supervises. [10]

An association represents a relationship that has a precisely defined meaning. The association can be labeled with the name of the association. If you want to assign a direction to the association's name, you can insert a triangle that points to the direction in which the name is supposed to be read. (...) An association indicates that objects of one class have a relationship with objects of another class, in which this connection has a specifically defined meaning (for example, "is flown with"). [11]

Aggregation

Aggregation is a stronger version of association. Unlike association, aggregation typically implies ownership and may imply a relationship between lifelines. Aggregations are usually read as "...owns a...". For example, if you had a classed named Window that stored its position and size in a Rectangle class, you would say the "Window owns a Rectangle." The rectangle may be shared with other classes, but the Window has an intimate relationship with the Rectangle. This is subtly different from a basic association; it has a stronger connotation. However, it's not the strongest relationship you can have between classes. If the relationship is more of a whole part (class A "...is part of..." class B), you should look at composition. [1]

You show an aggregation with a diamond shape next to the owning class and a solid line pointing to the owned class. [1]

Aggregation is the part-of relationship. It's like saying that a car has an engine and wheels as its parts. This sounds good, but the difficult thing is considering what the difference is between aggregation and association. [2]

(...) Aggregation is strictly meaningless; as a result, I recommend that you ignore it in your own diagrams. If you see it in other people's diagrams, you'll need to dig deeper to find out what they mean by it. Different authors and teams use it for very different purposes. [2]

Sometimes a class consists of a number of component classes. This is a special type of relationship called an aggregation. The components and the class they constitute are in a part-whole association. [3]

Aggregation is a type of association. An aggregate object consists of a set of component objects. [3]

Aggregation is transitive [3]

The weak form of aggregation is denoted with an open diamond. This relationship denotes that the aggregate class (the class with the white diamond touching it) is in some way the “whole”, and the other class in the relationship is somehow “part” of that whole. [5]

Many different types of aggregation or composition relationships have been proposed in data modeling, knowledge representation, and linguistics. For example, a-part-of (logically or physically), a-member-of (as in set membership), containedin, related-to, and associated-with. However, generally speaking, all aggregation relationships relate parts to wholes or parts to assemblies. For our purposes, we use the a-part-of or has-parts semantic relationship to represent the aggregation abstraction. For example, a door is a-partof a car, an employee is a-part-of a department, or a department is a-part-of an organization. [6]

Like the generalization relationship, aggregation relationships can be combined into aggregation hierarchies. For example, a piston is a-part-of an engine, while an engine is a-part-of a car. [6]

Aggregation means putting objects together to make a bigger object. Manufactured items usually form aggregations: for example, a microwave is made up of a cabinet, a door, an indicator panel, buttons, a motor, a glass plate, a magnetron, and so on. Aggregations usually form a part–whole hierarchy. Aggregation implies close dependency, at least of the whole to the part; for example, a magnetron is still a magnetron if you take it out of its microwave, but the microwave would be useless without the magnetron, because it wouldn’t be able to cook anything. [7]

As suggested, the distinction between association and aggregation can be subtle. The ‘What happens if you remove one of the objects?’ test can be helpful, but it doesn’t always solve the problem: hard thinking and experience are often needed. [7]

Aggregation: Strong association – an instance of one class is made up of instances of another class. [7]

An aggregation is a special kind of association — a "whole/part" relationship within which one or more classes are parts of a larger whole. A class can be aggregated to one or more other classes.

Using aggregation is an excellent way to establish a "pecking order" of complexity, with more complex classes aggregating less complex ones. For a system of any size, doing this can only help viewers of your models more easily understand the concepts that are important to them while enabling them to ignore concepts expressed at lower levels of detail.

An aggregation appears as a line with an open diamond at one end. The class next to the diamond is the whole class; the class at the other end of the line is the part class. [8]

An important property of aggregation is that the aggregated classes are still basically independent of the aggregating class. [8]

Shared aggregation means that the multiplicity at the composite end may be more than one, and is signified with a hollow diamond. It implies that the part may be simultaneously in many composite instances. (...) For instance, a UML package may be considered to aggregate its elements. But an element may be referenced in more than one package (it is owned by one, and referenced in others), which is an example of shared aggregation. [9]

In some cases, the presence of aggregation is obvious—usually in physical assemblies. But sometimes, it is not clear. On aggregation: If in doubt, leave it out. Here are some guidelines that suggest when to show aggregation:

Consider showing aggregation when:

• The lifetime of the part is bound within the lifetime of the composite — there is a create-delete dependency of the part on the whole.
• There is an obvious whole-part physical or logical assembly.
• Some properties of the composite propagate to the parts, such as the location.
• Operations applied to the composite propagate to the parts, such as destruction, movement, recording.

Other than something being an obvious assembly of parts, the next most useful clue is the presence of a create-delete dependency of the part on the whole. [9]

Composition

Composition represents a very strong relationship between classes, to the point of containment. Composition is used to capture a whole-part relationship. The "part" piece of the relationship can be involved in only one composition relationship at any given time. The lifetime of instances involved in composition relationships is almost always linked; if the larger, owning instance is destroyed, it almost always destroys the part piece. UML does allow the part to be associated with a different owner before destruction, thus preserving its existence, but this is typically an exception rather than the rule. [1]

A composition relationship is usually read as "...is part of...", which means you need to read the composition from the part to the whole. For example, if you say that a window in your system must have a titlebar, you can represent this with a class named Titlebar that "...is part of..." a class named Window. [1]

You show a composition relationship using a filled diamond next to the owning class and a solid line pointing to the owned class. [1]

The general rule is that, although a class may be a component of many other classes, any instance must be a component of only one owner. The class diagram may show multiple classes of potential owners, but any instance has only a single object as its owner. [2]

The "no sharing" rule is the key to composition. Another assumption is that if you delete the "whole", it should automatically ensure that any owned parts also are deleted. [2]

Composition is a good way of showing properties that own by value, properties to value objects, or properties that have a strong and somewhat exclusive ownership of particular other components. [2]

One form of aggregation involves a strong relationship between an aggregate object and its component objects. This is called composition. The key to composition is that the component exists as a component only within the composite object. For example, a shirt is a composite of a body, a collar, sleeves, buttons, buttonholes, and cuffs. Do away with the shirt and the collar becomes useless. Sometimes a component in a composite doesn’t last as long as the composite itself. The leaves on a tree can die out before the tree does. If you destroy the tree, the leaves also die. [3]

A composition is a special kind of aggregation. In a composite object the components exist only as part of the composite. (...) A composite is a strong type of aggregation. Each component in a composite can belong to just one whole. The components of a coffee table—the tabletop and the legs—make up a composite. The symbol for a composite is the same as the symbol for an aggregation except the diamond is filled. [3]

Composition relationships are a strong form of containment or aggregation. Aggregation is a whole/part relationship. In this case, Circle is the whole, and Point is part of Circle. However, composition is more than just aggregation. Composition also indicates that the lifetime of Point is dependent upon Circle. This means that if Circle is destroyed, Point will be destroyed with it. For those of you who are familiar with the Booch-94 notation, this is the Hasby-value relationship. [5]

Composition is a strong aggregation where the composed object is inside a single composite; the composed object is usually created at the same time as the composite and can be deleted at the same time. In UML, in order to emphasize that composition is stronger than aggregation, we use a black diamond instead of a white one. [7]

Composition: Strong aggregation – the composed object can’t be shared by other objects and dies with its composer. [7]

The difference between aggregation and composition is subtle. The differences relate to object sharing and object lifetimes. Recall that a composed object can never be part of more than one composite and dies with the composite, while an aggregated object can be shared and can outlive its aggregator. Although a car trundles out of the factory with a brand new engine inside, the engine may later be replaced, because it’s worn out, so the engine doesn’t necessarily die with the car; in contrast, the body of the car is an intrinsic part of the car – it’s the soul of the car, if you like, you can’t destroy the car without destroying the body (but you could always take the engine out first). The issue of sharing is not important in this example: although the body could never be part of two cars (not legally, anyway), the engine couldn’t either. [7]

Composition is a "strong" form of aggregation. There are two differences between composition and regular aggregation, as follows: Within a composition relationship, the whole and the parts have coincident lifetimes. This means that if a particular instance of the whole is destroyed, so are the instances of the parts. A class can only belong to one composition relationship at a time as a part. [8]

Composite aggregation, or composition, means that the part is a member of only one composite object, and that there is an existence and disposition dependency of the part on the composite. [9]

Composition is signified with a filled diamond. It implies that the composite solely owns the part. [9]

Generalization

A generalization relationship conveys that the target of the relationship is a general, or less specific, version of the source class or interface. Generalization relationships are often used to pull out commonality between difference classifiers. For example, if you had a class named Cat and a class named Dog, you can create a generalization of both of those classes called Animal. A full discussion of how and when to use generalization (especially versus interface realization) is the subject for an object-oriented analysis and design book and isn't covered here. [1]

Generalizations are usually read as "...is a...", starting from the more specific class and reading toward the general class. Going back to the Cat and Dog example, you would say "a Cat...is a...Animal" (grammar aside).[1]

You show a generalization relationship with a solid line with a closed arrow, pointing from the specific class to the general class. [1]

One class (the child class or subclass) can inherit attributes and operations from another (the parent class or superclass). The parent class is more general than the child class. (...) Object-orientation refers to this as inheritance. The UML also refers to this as generalization. (...) In the UML, you represent inheritance with a line that connects the parent class to the child class. On the part of the line that connects to the parent class, you put an open triangle that points to the parent class. This type of connection stands for the phrase "is a kind of". [3]

The generalization abstraction enables the analyst to create classes that inherit attributes and operations of other classes. The analyst creates a superclass that contains the basic attributes and operations that will be used in several subclasses. The subclasses inherit the attributes and operations of their superclass and can also contain attributes and operations that are unique just to them. For example, a customer class and an employee class can be generalized into a person class by extracting the attributes and operations they have in common and placing them into the new superclass, Person. In this way, the analyst can reduce the redundancy in the class definitions so that the common elements are defined once and then reused in the subclasses. Generalization is represented with the a-kind-of relationship, so that we say that an employee is a-kind-of person. [6]

Inheritance: A subclass inherits all of the attributes and behavior of its superclass(es). [7]

Generalization refers to a relationship between a general class (the superclass or parent) and a more specific version of that class (the subclass or child). You can think of the subclass as being a "kind of" the superclass. A generalization appears as a line with an open triangle at one end. The class next to the triangle is the parent/superclass; the class at the other end of the line is the child/subclass. [8]

Realization

A realization is an association between a class and an interface, a collection of operations that a number of classes can use. An interface is represented as a class with no attributes. To distinguish it from a class whose attributes have been elided from the diagram, the keyword «interface» appears above the interface’s name or an uppercase “I” precedes the interface’s name. Realization is represented in the UML as a dashed line that connects the class to the interface, with an open triangle adjoining the interface and pointing to it. [3]

References:

[1] Dan Pilone, Neil Pitman, UML 2.0 in a Nutshell, O'Reilly, 2005
[2] Martin Fowler, UML Distilled: A brief guide to the standard object modeling language, 3rd edition, Addison-Wesley Professional, 2004
[3] Joseph Schmuller, Teach Yourself UML in 24 Hours, Sams Publishing, 2004
[4] OMG UML Superstructure Version 2.4.1, OMG, 2011
[5] Robert C. Martin, UML Tutorial
[6] Alan Dennis, Barbara Haley Wixom and David Tegarden, System Analysis and Design with UML Version 2.0 - An Object-Oriented Approach, John Wiley & Sons Ltd, 2005
[7] Mike O’Docherty, Object-Oriented Analysis and Design - Understanding System Development with UML 2.0, John Wiley & Sons Ltd, 2005
[8] Kendall Scott, Fast Track UML 2.0, Apress, 2004
[9] Craig Larman, Applying UML and Patterns - An Introduction to Object-Oriented Analysis and Design and the Unified Process 2nd ed, Prentice Hall, 2001
[10] Howard Podeswa, UML for the IT Business Analyst: A Practical Guide to Object-Oriented Requirements Gathering, Thomson Course Technology PTR, 2005
[11] Patrick Grässle, Henriette Baumann, Philippe Baumann, UML 2.0 in Action - A Project-Based Tutorial, Packt Publishing Ltd, 2005
[12] Scott W. Ambler, The Elements of UML 2.0 Style, Cambridge University Press, 2005

Circular references in constructors

2012-01-18T09:56:00.000Z

It is not uncommon to have situation when class A references class B and vice versa. This is known as circular dependency and is resolved by using forward declarations.

It is valid and safe to use mutually referenced classes if we initialize references after fully creating classes' instances. But what happens if references are assigned (and probably used) in constructors? Constructor of first class initializes reference to an instance of the second class that is yet to be created...This sounds silly and we can expect all sorts of things - from compile-time and run-time errors to programs running perfectly fine (well, if we are lucky enough...).

References can be implemented as pointer or reference types.

Let's have a look at pointer-based implementation and let us assume we have structures (or classes) implemented like this:

S1.h:

S1.cpp:

S2.h:

S2.cpp:

main.cpp:

We had to pass 0 to S1 constructor as s2 had not yet been declared nor created. This makes S1 constructor to raise access violation exception when it tries to dereference m_pS2 in order to call S2 methods.

If we used references instead of pointers, we would not even have a chance to write the code that compiles:

S3.h:

S3.cpp:

S4.h:

S4.cpp:

main.cpp:

A simple fact that we cannot have a reference (or address) of the object that hasn't yet been created leads to conclusion that it is impossible to create instances of mutually dependent classes where references must be initialized in constructor.

But there is one case when this is actually possible. Possible but not safe. If these structures are members of another (container) structure, it is possible to initialize references in container's constructor initializer list.

main.cpp:

Output:

S1::S1()
S2::Foo()
S2::PrintVal(): -858993460
S2::S2()
S1::Foo()
S1::PrintVal(): 1
S5::PrintVals()
S2::PrintVal(): 2
S1::PrintVal(): 1
S3::S3()
S4::Foo()
S4::PrintVal(): -858993460
S4::S4()
S3::Foo()
S3::PrintVal(): 1
S6::PrintVals()
S4::PrintVal(): 2
S3::PrintVal(): 1

We can see here that:

It is possible to set circular references between two classes during their construction if they are members of some container class
It is not safe to use circular references in constructors of their classes: dereferencing (and using) reference of the object that is not fully constructed leads to undefined behaviour. In our examples, the wrong value of the member of the class that had not yet been constructed was printed (-858993460 instead of 2)
It is safe to use circular references once objects are fully created S5::PrintVals() and S6::PrintVals() print correct values of members of referenced objects. This is similar to the case when some container class A has a member B that must be initialized with the pointer/reference to A (this or *this): that is safe as long as B's constructor doesn't try to access A's members or call A's methods. B has to wait for A to be completely constructed in order to use A's reference safely

One additional note: it is always a good practice to decouple classes (break dependencies between them) as much as possible. This is usually done by using interfaces or some other patterns (e.g. Observer pattern).

Prefer compile-time to run-time value range checks: use enumerations

2012-01-10T12:38:00.000Z

In a perfect world, compiler should be able to detect all errors in the code. If types mismatch or value is out of the valid range - compiler should complain. How can we help compiler to achieve this? One answer is: by defining our custom types.

Enumerations

When we define enumeration, we are introducing a new type. Let's say some integer variable can be assigned only certain values, from a predefined set. Function that assigns value to a variable could look like this:

Ok, what happens if someone writes

This code compiles fine but it sets variable to a value out of the valid range and this can lead to some logical errors.

How can we improve this code? Obviously, we can check whether value is valid. If it is not, we can either throw exception, set variable to some default value or just quietly return from a function:

Each time this function is called it will use CPU resources to perform value check. But is it necessary? Can we make this function more optimal in a run-time? Yes, we can: by moving value check from run-rime to compile time! If we define our custom type - enumeration - which defines valid range, we will be able to use compiler to find all places where invalid value is passed:

SetLevel(2) will cause compiler to report an error.

One example of the real-life usage of this approach could be writing a wrapper around Windows Thread API. E.g. SetThreadPriority has an argument nPriority which is of type int and so can accept any integer value despite the fact that valid values are from a predefined set (THREAD_PRIORITY_ABOVE_NORMAL = 1, THREAD_PRIORITY_BELOW_NORMAL = -1, THREAD_PRIORITY_HIGHEST = 2, ...). Passing invalid integer values can be prevented by introducing our enumeration which enumerates all valid values for thread priority:

NOTE: enum value is implicitly casted to int but int value must be explicitly casted to enum type.

Finite State Machine in C++

2011-12-16T17:43:00.000Z

In my article "Finite State Machine in C" I gave a short introduction to Finite State Machines (FSM) and demonstrated two possible implementations of the Car state machine model.

In this article I will show C++ implementation of the same model, by using State Pattern. All state classes are derived from an abstract base class CState and each of them implements public method HandleEvent(EVENT evt). CSMManager class is a State Machine Manager and represents the core of our State Machine: it receives events and dispatches them to the current state for handling. Its private member m_pCurrState is a pointer to the CState base class but it always points to actual state objects. State transition is implemented as its reassignment to a different state object (object's address). This happens when some event occurs. Behaviour of this model is event-driven and, in contrast to C implementations, state transition control is not centralized here - it is not the State Manager who takes care of which state is going to be the next one. Current state decides on that itself, depending on its current conditions and events it receives.

Events.h:

States.h:

State.h:

StateTurnedOff.h:

StateTurnedOff.cpp:

StateIdle.h:

StateIdle.cpp:

StateMoving.h:

StateMoving.cpp:

StateInvalid.h:

StateInvalid.cpp:

SMManager.h:

SMManager.cpp:

main.cpp:

Output:

CStateTurnedOff::OnEntry()
Event received: EVENT_IGNITE
   Whoooa! I'm turned on!
CStateTurnedOff::OnExit()

CStateIdle::OnEntry()
Event received: EVENT_ACCELERATE
   Yipee! I'm accelerating!
CStateIdle::OnExit()

CStateMoving::OnEntry()
Event received: EVENT_BRAKE
   Whoops! Was I too fast?
CStateMoving::OnExit()

CStateIdle::OnEntry()
Event received: EVENT_TURN_OFF
   That was probably enough...
CStateIdle::OnExit()

CStateTurnedOff::OnEntry()
CStateTurnedOff::OnExit()

Note that State Manager's member which refers to the current state (m_pCurrState) is not of reference type (CState&) but a pointer (CState*). This is one of the cases where we MUST use pointer instead of reference because we want to have a variable which reffers to different objects throughout the execution and as re-seating the reference is not allowed, the only option is using a pointer. Please refer Parashift's FAQ on References and this SO question.

The reason for introducing m_prevStateID is that sometimes state machine (or some of its states) needs to know what was its previous state. Variable which keeps track of the previous state should not be of type reference (m_prevState : CState&) or pointer (m_pPrevState : CState*) as current state should not be able to access (members) of other states. It is therefore enough if it holds only the ID of the previous state.

Note that base abstract class CState declares OnEntry() and OnExit() methods - those which are executed when entering and leaving state. Current state executes HandleEvent(EVENT evt) each time it receives some event.

Endianness: how does CPU read bytes from memory?

2011-12-09T11:06:00.001Z

The simplest example is enough to give you the idea: CPU needs to read 2-byte data type from memory. The following example shows how do Big and Little endian machines read variable of type unsigned short from memory:

main.cpp

Output:

Memory layout:
arr[0] = 0xab
arr[1] = 0xcd
val (simple cast on little endian host) = 52651
val (as interpreted by little endian cpu) = 52651
val (as interpreted by big endian cpu) = 43981

Host endianness and data transfer over the network

2011-12-08T10:05:00.001Z

Network components talk to each other by sending messages which are simply arrays of bytes. In order to understand them, parties in conversation need to know the communication protocol which defines message format and the length, order and the meaning of its parts.

Typically, message would comprise header and payload. Header can contain information about message itself, protocol version and information about the sender and receiver. Payload is actually information that sender wants to pass to receiver.

The simplest and shortest message one host can send is a message of a 1-byte length. In this case, protocol only needs to define how is this byte treated - as a character, signed or unsigned number. For example, if protocol says that message contains value of type unsigned char, and the message is 0x8b, receiver will treat this as a positive integer, of value 139. If that was a value of signed char, receiver would understand that this is a negative integer, -117.

There is one problem for messages made of two or more bytes. Bytes are send and received in the same order they are written in the sending buffer. But the way how are bytes copied from register to memory (buffer) and vice versa can be different on different hosts and this depends on their endianness. If sender has a big endian (BE) CPU and receiver has a small endian (SE) CPU, receiver might interpret received values in a wrong way.

Let's look at the case when the message comprises of 2-byte integer value, let's say of type unsigned short. This type has a range of values between 0 and 65535 (0x0000 and 0xffff). If BE sender wants to send value 0xabcd (43981) it will copy this value from registry to buffer keeping the same byte order and buffer will be like this: | 0xab | 0xcd |. Most significant byte (MSB) is at the lower address in memory. The other side will receive bytes in the same order. When copying bytes to the registry, BE receiver will treat the byte from the lowest memory address as the MSB and put it first so the registry will filled with bytes in the same order they are in the memory (0xabcd) and everything would be fine. But LE receiver will treat byte from the lowest address as the Least Significant Byte (LSB) and put it at the last position in the registry - it would swap the order and read received value as 0xcdab (52651), which is wrong! Sender should know the endianness of the client so can send bytes in the correct order, but that is impractical.

Solution to this is a simple rule: sender should always send bytes in big endian order (network byte order) and receiver should always convert received bytes from network to its own byte order. This makes sending and receiving code portable.

Both Windows and *NIX networking frameworks offer helper functions which are able to convert integers from host to network byte order and vice versa. They are:

uint32_t htonl(uint32_t hostlong);
uint16_t htons(uint16_t hostshort);
uint32_t ntohl(uint32_t netlong);
uint16_t ntohs(uint16_t netshort);

Obviously, if host has network byte order (big endian), no conversion would take place, no matter whether it is on the sending or receiving side.

Sending and receiving buffers can be declared as char or unsigned char arrays. Values transported could be of signed or unsigned types. I made a set of several utility functions that insert and export values of desired integer types into/out from sending/receiving (probably socket) buffers. Prior to inserting, values are converted to network byte order (big endian) and after extraction, values are converted from network to host byte order. Tests prove that hton/ntoh functions can be applied both to signed and unsigned types as all they do is actually swapping bytes (if necessary).

NetBuffUtilCore.h:

NetBuffUtil.h:

NetBuffUtil.cpp:

main.cpp:

Output:

unsigned char buff
Original (unsigned short): 43981
Received val = 43981

char buff
Original (unsigned short): 43981
Received val = 43981

unsigned char buff
Original (short): -31234
Received val = -31234

char buff
Original (short): -31234
Received val = -31234

unsigned char buff
Original (unsigned long): 2882343476
Received val = 2882343476

char buff
Original (unsigned long): 2882343476
Received val = 2882343476

unsigned char buff
Original (long): -1107401523
Received val = -1107401523

char buff
Original (long): -1107401523
Received val = -1107401523

To avoid dependency on Winsock library, I implemented a function which swaps bytes for a given type (well, template should be constrained to only integer types...):

EndiannessUtil.h:

main.cpp:

So far, we were focused on transfer of integer types. What if message payload needs to contain strings, or, mashup of strings and integers?

Let's say that we need to send some ASCII string and some unsigned long number. Protocol should define message payload like this:

|L0|L1|S1|S1|S2|........|SK|N0|N1|N2|N3|

|L0|L1| - 2 bytes for unsigned short value that defines string length (K bytes)
|S1|S1|S2|........|SK| - string (K bytes)
|N0|N1|N2|N3| - 4 bytes for unsigned long number

Both integers should be converted to the network byte order prior to writing into sending buffer. But string does not need to be changed - that is ASCII string and each character is placed in a single byte. Receiving side will first read 2 bytes of payload, extract string length (K), allocate memory for string (K bytes) and then read (copy) next K bytes from receiving buffer into the string buffer. After that, receiver will read next 4 bytes and convert them from network byte order before passing it for further processing.

If sending Unicode string, we need to take care about endianness again as some of its characters use two or more bytes. Our protocol will define encoding applied (e.g. UTF-8 or UTF-16) but this time sender needs to send additional information as well - its endianness. This information is contained in Byte Order Mark (BOM) sequence which is prepended to our string. BOM helps Unicode decoder on the client side to decide whether to swap or not bytes for multi-byte characters.

Links and references:
htons(), htonl(), ntohs(), ntohl() (Beej's guide)
htons function (MSDN)
htonl function (MSDN)
ntohl function (MSDN)
ntohs function (MSDN)
Linux functions
Encodings and Unicode (Python)
Byte Order (Codecs)

How to get notified when network adapters' IP addresses change?

2011-11-04T20:59:00.000Z

TCP/IP networking software requires at least one network adapter bounded to TCP/IP protocol stack. Each physical network card has unique MAC address and static or dynamic IP address. Static address (one or possibly more) is configured manually and dynamic address is assigned by Dynamic Host Configuration Protocol (DHCP) server (if DHCP is enabled; Obtain IP address automatically is ticked in TCP/IPv4 Properties window). Operating system maintains table which maps IP addresses to network interfaces. Use ipconfig command in command prompt window to display that table. If your adapter has DHCP enabled and you unplug/plug network cable (if using LAN adapter), disable/enable network adapter through adapter settings, issue ipconfig /release or /renew command, get out of/into WiFi range (if using WiFi adapter)...your adapter will loose existing or get a new IP address. NIC to IP address table will change.

Networking applications often need to be aware when changes in this table occur. Windows API function NotifyAddrChange notifies caller on this event. Here is an example of how to call it synchronously (when it's blocking):

This is the output if we unplug network cable and then plug it back again:

Waiting for IP Table change or termination request...
Press ENTER to terminate listening for changes in IP address table...
WaitForSingleObject(waitObjects) returned WAIT_OBJECT_0 + 1 (overlap.hEvent is s
ignaled)
Num Entries: 2

Interface Index[0]: 17
IP Address[0]: 192.168.56.1
Subnet Mask[0]: 255.255.255.0
BroadCast[0]: 1.0.0.0(1)
Reassembly size[0]: 65535
Type and State[0]: Primary IP Address
Network interface name: VirtualBox Host-Only Ethernet Adapter
Network interface type: ETHERNET
MAC Address: 08-00-27-00-68-56

Interface Index[1]: 1
IP Address[1]: 127.0.0.1
Subnet Mask[1]: 255.0.0.0
BroadCast[1]: 1.0.0.0(1)
Reassembly size[1]: 65535
Type and State[1]: Primary IP Address
LOCALHOST interface
Network interface name: Software Loopback Interface 1
Network interface type: LOOPBACK

Waiting for IP Table change or termination request...
WaitForSingleObject(waitObjects) returned WAIT_OBJECT_0 + 1 (overlap.hEvent is s
ignaled)
Num Entries: 3

Interface Index[0]: 10
IP Address[0]: 192.168.253.122
Subnet Mask[0]: 255.255.255.0
BroadCast[0]: 1.0.0.0(1)
Reassembly size[0]: 65535
Type and State[0]: Primary IP Address Dynamic IP Address
Network interface name: Intel(R) 82566DC Gigabit Network Connection
Network interface type: ETHERNET
MAC Address: 00-19-d1-1b-e0-88

Interface Index[1]: 17
IP Address[1]: 192.168.56.1
Subnet Mask[1]: 255.255.255.0
BroadCast[1]: 1.0.0.0(1)
Reassembly size[1]: 65535
Type and State[1]: Primary IP Address
Network interface name: VirtualBox Host-Only Ethernet Adapter
Network interface type: ETHERNET
MAC Address: 08-00-27-00-68-56

Interface Index[2]: 1
IP Address[2]: 127.0.0.1
Subnet Mask[2]: 255.0.0.0
BroadCast[2]: 1.0.0.0(1)
Reassembly size[2]: 65535
Type and State[2]: Primary IP Address
LOCALHOST interface
Network interface name: Software Loopback Interface 1
Network interface type: LOOPBACK

Waiting for IP Table change or termination request...

WaitForSingleObject(waitObjects) returned WAIT_OBJECT_0 (hTerminateEvent is sign
aled)
WaitForSingleObject(hThread) returned WAIT_OBJECT_0 (event is signaled)
Press ENTER to exit...

How to include stdafx.h conditionally?

2011-10-27T16:39:00.001+01:00

Don't try it as that's not possible!

If you try to put #include "stdafx.h" between #ifdef and #endif, you'll end up with error C1020: unexpected #endif. You need to include stdafx.h at the beginning of any source file in your project, apart from those files for which using precompiled headers is turned off.

There is one situation where this feature - setting using precompiled headers at the file level - comes very handy. Let's say we have some code file which does not include stdafx.h and we need to share it between project which uses precompiled headers - P1, and project which doesn't - P2. If we add that file to P1, this project won't compile - compiler will complain with fatal error C1010: unexpected end of file while looking for precompiled header. We cannot include stdafx.h at the beginning of that file either as then P2 won't compile - it does not have stdafx.h. The only solution is to turn off using precompiled headers for that particular file.

Finite State Machine in C

2011-10-25T15:57:00.002+01:00

Finite State Machine is a way of modelling behaviour of some entity that can have a (finite) set of states. Depending on the received event, entity performs some action and changes its state (or remains in the current one).

Let's say we want to model a behaviour of some simple car. I call it "simple" as it has only ignition switch, accelerator and brake. Driver can turn it on, then accelerate, brake and, at the end of the journey, turn it off. If not careful, driver can break the car - if tries to turn it on (again) while driving. Driver's actions are events - inputs of our model. Car can be turned off, idling, moving or broken - and this is a set of our car's states. So, car is in some state, it reacts on driver's command (event), performs some action and goes into the next state.

We have a finite set of states and events and can draw a diagram which precisely define state transitions (state transition diagram):

Now, how to implement this model and show how this state machine changes states after receiving events?

Each state can be represented as unique number - its code, or ID. The similar thing is with events. As we have finite number of both states and events, we can use enum type to represent them: one variable will be of enum STATE type and contain the ID of the current state and another variable will be of type enum EVENT and will contain the most recent event this system received. Initially, our car is turned off so the state variable will be set to STATE_TURNED_OFF. After this simple initialization we just need to wait for events and handle them in accordance to the given transition diagram. Events can be obtained from a keyboard or some other source and they are usually kept in a queue as sometimes a new event can be received before processing of the previous one is finished. In this example, in order to keep things simple, I'm gonna assume that processing is fast enough and will just create a predefined set of events and put them in an array.

As we have repetitive action - receiving and handling events - we'll put it in a loop. If our events source is keyboard and we don't know how many events will user issue, we can use while-loop and CTRL-C as a loop termination command. In this example, we have an array of events which is of predefined (known in advance) size so we can use for-loop. Inside this loop, we need to place event processing code for each event, received in each state. This means we will have switch-statement inside another switch-statement. So, here's the code:

main.c:

Output:

Whoooa! I'm turned on!
Yipee! I'm accelerating!
Whoops! Was I too fast?
That was probably enough...

Having a switch inside a switch looks a bit complex and difficult to maintain. If we add a new state, we need to add a new case-branch for each event. In the code above it would mean we need to make changes at 4 different places in the code! Not good!

A solution for this is a state transition table. It is basically a table in which each state has its column and each event has its row. Table elements are pairs action/next-state - let's put them in some structure called TRANSITION. If transition table is called trans_tbl its element, trans_tbl[evt][state] is of type TRANSITION and action is a function called during transition and next-state is the state our model goes into for the current event. Code tells this better:

main.c:

Output is the same:

Whoooa! I'm turned on!
Yipee! I'm accelerating!
Whoops! Was I too fast?
That was probably enough...

The code has shrunk and become easier to understand and maintain: if we want to add a new event or a state, we just need to change transition table (trans_tbl) - we don't need to touch the code in a loop!

My article "Finite State Machine in C++" shows how to use OOP and State design pattern in order to implement FSM described here.

Links and references:
Finite-state machine (Wikipedia)
UML Tutorial: Finite State Machines

Reading XML with Guththila

2011-10-14T14:15:00.000+01:00

Guththila is Apache XML parser for Axis2/C.

I've been playing with Guththila recently and just want to share code which demonstrates how to use Guththila in a standalone application, GuththilaTest. It will read data from the following XML file:

books.xml:

<?xml version="1.0" ?>
<books>
<Genre Name="Biography">
<Author Name="Michael Moore">
<Book Name="Here Comes Trouble" ISBN="9780713997019" PublishingDate="13-Sep-2011"/>
</Author>
<Author Name="Alan Sugar">
<Book Name="Way I See it" ISBN="9780230760899" PublishingDate="29-Sep-2011"/>
</Author>
</Genre>
<Genre Name="Fiction">
<Author Name="Ivo Andric">
<Book Name="Bridge Over the Drina" ISBN="9781860460586" PublishingDate="05-Apr-1994"/>
</Author>
<Author Name="Fyodor Dostoyevsky">
<Book Name="Crime and Punishment" ISBN="9780955816949" PublishingDate="30-Oct-2008"/>
<Book Name="Brothers Karamazov" ISBN="9780140449242" PublishingDate="27-Feb-2003"/>
</Author>
</Genre>
</books>

We need to download Axis2/C binary package (or its source and build binaries ourselves) as Guththila requires axutil.dll and guththila.dll in a runtime and application that uses Guththila must be linked against its static libraries axutil.lib and guththila.lib.

Axis2/C manual suggest placing Axis2/C package at some location your disk (e.g. c:\axis2c) and setting environment variable AXIS2C_HOME to that path, plus adding %AXIS2C_HOME%/lib to Path environment variable so any application can find Axis2C libraries.

In this example, I will use minimalistic approach, putting all necessary libraries (axutil.dll, guththila.dll) in application's directory.

If path to necessary Axis2C DLLs is not in Path environment variable and if necessary DLLs are not in the application's directory, following message appears if you try to run the app:

---------------------------
GuththilaTest.exe - System Error
---------------------------
The program can't start because axutil.dll is missing from your computer. Try reinstalling the program to fix this problem.
---------------------------
OK
---------------------------

We need to create environment variable, and we want to have log file as well so we need to call axutil_env_create_all() function.

This algorithm explains the logic of the Axis2/C log file creation:

pass log file string to axutil_env_create_all() as an argument

axutil_env_create_all() forwards that string to axutil_log_create()

if (string is full path to log file, including its name)
   axutil_log_create() creates log file at the proved path
else (string is just log file name)
   axutil_log_create() tries to read path from AXIS2C_HOME environment variable
   if AXIS2C_HOME path obtained
      axutil_log_create() creates log file at AXIS2C_HOME/logs path
   else
     axutil_log_create() creates log file in the current directory

I don't want to change environment variables so just place axutil.dll and guththila.dll (together with books.xml) in the same directory with GuththilaTest.exe. As I don't set AXIS2C_HOME environment variable, Axis creates log file in the same directory.

So here is the code. ReadXML(...) outputs formatted content of the XML file to the standard output. GetBookInfo(...) performs search for a particular node. Each parsing session (going through XML) requires (re)initialized parser. guth_init(...) is therefore called before and guth_clean() after each of these two functions. GetStrLen(), CopyStrRealloc() and PrintSpaces() are some helper functions.

main.c:

This is the output:

..\GuththilaTest\Debug>GuththilaTest.exe
AXIS2C_HOME is not set - log is written to . dir
<books>
<Genre Name="Biography">
<Author Name="Michael Moore">
<Book PublishingDate="13-Sep-2011" ISBN="9780713997019" Name="Here Comes Tro
uble"/>
</Author>
<Author Name="Alan Sugar">
<Book PublishingDate="29-Sep-2011" ISBN="9780230760899" Name="Way I See it"/
>
</Author>
</Genre>
<Genre Name="Fiction">
<Author Name="Ivo Andric">
<Book PublishingDate="05-Apr-1994" ISBN="9781860460586" Name="Bridge Over th
e Drina"/>
</Author>
<Author Name="Fyodor Dostoyevsky">
<Book PublishingDate="30-Oct-2008" ISBN="9780955816949" Name="Crime and Puni
shment"/>
<Book PublishingDate="27-Feb-2003" ISBN="9780140449242" Name="Brothers Karam
azov"/>
</Author>
</Genre>
</books>

Details for book "Brothers Karamazov" found: ISBN="9780140449242", PublishingDat
e="27-Feb-2003"
..\GuththilaTest\Debug>

And this is the content of the log file:

[Fri Oct 14 19:49:18 2011] [debug] c:\development\research\c\guththilatest\guththilatest\main.c(595)
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(534) reader created
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(517) DebugReader()
buff_size=-1163005939
type=1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(553) parser created
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(502) DebugParser()
guththila_event=-1
last_start=-1
name=0
next=0
status=1

[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(517) DebugReader()
buff_size=-1163005939
type=1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(103) GUTHTHILA_START_DOCUMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "books"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Biography"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Michael Moore"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(120) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "13-Sep-2011"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "9780713997019"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Here Comes Trouble"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Alan Sugar"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(120) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "29-Sep-2011"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "9780230760899"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Way I See it"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Fiction"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Ivo Andric"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(120) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "05-Apr-1994"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "9781860460586"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Bridge Over the Drina"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(115) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Fyodor Dostoyevsky"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(120) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "30-Oct-2008"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "9780955816949"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Crime and Punishment"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(120) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(142) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(149) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "27-Feb-2003"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "9780140449242"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(177) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(189) AttribVal: "Brothers Karamazov"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(239) GUTHTHILA_SPACE
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(97) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(212) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(217) Name: "books"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(566) guththila_reader_free() ok
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(573) guththila_un_init() ok
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(534) reader created
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(517) DebugReader()
buff_size=-1163005939
type=1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(553) parser created
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(502) DebugParser()
guththila_event=-1
last_start=-1
name=0
next=0
status=1

[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(517) DebugReader()
buff_size=-1163005939
type=1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(267) GetBookInfo()
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(268) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(278) GUTHTHILA_START_DOCUMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 0
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "books"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(322) Current node is Genre node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Biography"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Biography"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(295) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(468) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(473) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(295) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(468) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(473) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(468) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(473) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Genre"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(318) Is current node Genre node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(322) Current node is Genre node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Fiction"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Fiction"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(400) Found Genre node with Name "Fiction"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(328) Is current node Author node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(332) Current node is Author node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Ivo Andric"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Ivo Andric"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(295) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(328) Is current node Author node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(468) GUTHTHILA_END_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(473) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 2
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(290) GUTHTHILA_START_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Author"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(328) Is current node Author node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(332) Current node is Author node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 1
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Fyodor Dostoyevsky"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Fyodor Dostoyevsky"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(411) Found Author node with Name "Fyodor Dostoyevsky"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(295) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(338) Is current node Book node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(343) Current node is Book node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "30-Oct-2008"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(441) PublishingDate: "30-Oct-2008"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(451) pBookInfo->pszPublishingDate = "30-Oct-2008"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "9780955816949"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(427) ISBN: "9780955816949"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(437) pBookInfo->pszISBN = "9780955816949"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Crime and Punishment"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Crime and Punishment"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(272) Number of elements in guththila stack: 4
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(295) GUTHTHILA_EMPTY_ELEMENT
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(313) Name: "Book"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(338) Is current node Book node?
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(343) Current node is Book node
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(353) Number of attributes: 3
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "PublishingDate"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "27-Feb-2003"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(441) PublishingDate: "27-Feb-2003"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(451) pBookInfo->pszPublishingDate = "27-Feb-2003"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "ISBN"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "9780140449242"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(427) ISBN: "9780140449242"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(437) pBookInfo->pszISBN = "9780140449242"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(370) AttribName: "Name"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(385) AttribVal: "Brothers Karamazov"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(393) Name="Brothers Karamazov"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(421) Found Book node with Name "Brothers Karamazov"
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(495) ~GetBookInfo()
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(566) guththila_reader_free() ok
[Fri Oct 14 19:49:18 2011] [debug] \guththilatest\main.c(573) guththila_un_init() ok

Please be aware that Guththila is not intended for direct use but through its wrapper, axis2_parser [link]. That is probably the reason why there is no documentation about it available on the Internet.

axis2_parser is XML parser abstraction layer which can be either guththila or libxml2 wrapper. In the first case (in Axis2/C binary package), axis2_parser.dll depends on guththila.dll. In the second case (in custom Axis2/C builds), axis2_parser.dll depends on libxm2.dll, zlib1.dll and iconv.dll.

What to do when sending message to some window fails or crashes the application

2011-10-13T11:03:00.000+01:00

You want to send a message from one window to another by calling CWnd::SendMessage(...) or CWnd::PostMessage(...) and application crashes during these calls. How to find the cause of the crash?

We first need to determine the nature of the crash. Open crash dump, read message in Windows Debugger Dialog Box, read log file (if any). Functions above are called on the window through its pointer so check whether pointer is valid (not NULL - in which case you'll have access violation exception). Get window's handle and check whether it's valid (IsWindow(...)). If message is supposed to be sent to window's parent/owner, make sure that sending and receiving window are of proper type and in desired relation (parent/child or owner/owned).

It is very important to understand types of windows and relationships between them. They are all set at the time of window creation.

When creating some window with Create(...)/CreateEx(...) we need to pass two important arguments to these functions:
1) window styles
2) parent/owner window

Window styles define the nature (type) of the window and its appearance. There are three types of windows: overlapped, pop-up and child. For example, main application window is an overlapped window, which has some embedded controls (e.g. buttons) and these controls are child windows. When we press some of those buttons, a dialog box can appear and dialog box is a pop-up window. Each of these three types has its own flag within Window styles and they are defined in WinUser.h: WS_OVERLAPPED (0x00000000L), WS_POPUP (0x80000000L), WS_CHILD (0x40000000L). Window style can have only one of these flags set (e.g. window cannot be pop-up and child at the same time). If you omit setting style, your window will be overlapped by default and no matter the fact you passed the pointer/handler of some window as its e.g. parent, you might not get expected behaviour as this window will not actually be of a child type!

When passing pointer or handler to parent/owner window, make sure that pointer is not NULL, and that handler is a valid handler of parent/owner at the time of the creation of child/owned window (use IsWindow()).

Do the same for window you're calling SendMessage/PostMessage on.

You can use this helper function which analyses some arbitrary window:

WndHelper.h:

#ifndef _WNDHELPER_H
#define _WNDHELPER_H

#include <afxwin.h>

// Usage:
// CWnd* pWnd = ...
// AnalyzeWnd(pWnd);
void AnalyzeWnd(const CWnd* pWnd);

#endif // _WNDHELPER_H

WndHelper.cpp:

#include "Include\WndHelper.h"

void AnalyzeWnd(const CWnd* pWnd)
{
TRACE(_T("AnalyzeWnd()"));

if(!pWnd)
{
TRACE(_T("pWnd is NULL!"));
return;
}

//
// Get Desktop
//

CWnd* pWndDesktop = pWnd->GetDesktopWindow();

if(pWndDesktop)
{
TRACE(_T("GetDesktopWindow() returned valid window pointer. pWndDesktop = %p"), pWndDesktop);

HWND hWndDesktop = pWndDesktop->GetSafeHwnd();
TRACE(_T("hWndDesktop = %p"), hWndDesktop);
}
else
{
TRACE(_T("GetDesktopWindow() returned NULL!"));
}

//
// Analyze Window
//

TRACE(_T("pWnd = %p"), pWnd);

HWND hWnd = pWnd->GetSafeHwnd();

if(::IsWindow(hWnd))
{
TRACE(_T("GetSafeHwnd() returned valid window handle. hWnd = %p"), hWnd);
}
else
{
TRACE(_T("GetSafeHwnd() returned INVALID window handle!"));
}

if(::IsWindow(pWnd->m_hWnd))
{
TRACE(_T("m_hWnd is a valid window handle. pWnd->m_hWnd = %p"), pWnd->m_hWnd);

TRACE(_T("Window styles: "));
LONG lStyle = ::GetWindowLong(pWnd->m_hWnd, GWL_STYLE);

if(lStyle == WS_OVERLAPPED) // 0
{
TRACE(_T("\t\tWS_OVERLAPPED (0)"));
}
else
{
if((lStyle & WS_POPUP) == WS_POPUP)
TRACE(_T("\t\tWS_POPUP"));

if((lStyle & WS_CHILD) == WS_CHILD)
TRACE(_T("\t\tWS_CHILD"));

if((lStyle & WS_VISIBLE) == WS_VISIBLE)
TRACE(_T("\t\tWS_VISIBLE"));

if((lStyle & WS_DISABLED) == WS_DISABLED)
TRACE(_T("\t\tWS_DISABLED"));

if((lStyle & WS_CAPTION) == WS_CAPTION)
TRACE(_T("\t\tWS_CAPTION"));

if((lStyle & WS_BORDER) == WS_BORDER)
TRACE(_T("\t\tWS_BORDER"));

if((lStyle & WS_DLGFRAME) == WS_DLGFRAME)
LOGGER_PRINTF(Debug, _T("\t\tWS_DLGFRAME"));

if((lStyle & WS_SYSMENU) == WS_SYSMENU)
TRACE(_T("\t\tWS_SYSMENU"));

// todo: add checks for other styles...
}

// todo: check extended styles
// LONG lStyleEx = GetWindowLong(GetSafeHwnd(), GWL_EXSTYLE);
}
else
{
TRACE(_T("pWnd->m_hWnd is an INVALID window handle!"));
}

hWnd = pWnd->m_hWndOwner;

if(::IsWindow(hWnd))
{
TRACE(_T("m_hWndOwner is a valid window handle. m_hWndOwner = %p"), hWnd);
}
else
{
TRACE(_T("m_hWndOwner is an INVALID window handle!"));
}

//
// Analyze Parent
//

CWnd* pWndParent = pWnd->GetParent();

if(pWndParent)
{
TRACE(_T("GetParent() returned valid pointer. pWndParent = %p"), pWndParent);

HWND hWnd = pWndParent->GetSafeHwnd();

if(::IsWindow(hWnd))
{
TRACE(_T("GetSafeHwnd() returned valid window handle. hWnd = %p"), hWnd);
}
else
{
TRACE(_T("GetSafeHwnd() returned INVALID window handle!"));
}
}
else
{
TRACE(_T("GetParent() returned NULL!"));
}

CWnd* pWndParentOwner = pWnd->GetParentOwner();

if(pWndParentOwner)
{
TRACE(_T("GetParentOwner() returned valid pointer. pWndParentOwner = %p"), pWndParentOwner);

HWND hWnd = pWndParentOwner->GetSafeHwnd();

if(::IsWindow(hWnd))
{
TRACE(_T("GetSafeHwnd() returned valid window handle. hWnd = %p"), hWnd);
}
else
{
TRACE(_T("GetSafeHwnd() returned INVALID window handle!"));
}
}
else
{
TRACE(_T("GetParentOwner() returned NULL!"));
}

//
// Analyze Owner
//

CWnd* pWndOwner = pWnd->GetOwner();

if(pWndOwner)
{
TRACE(_T("GetOwner() returned valid pointer. pWndOwner = %p"), pWndOwner);

HWND hWnd = pWndOwner->GetSafeHwnd();

if(::IsWindow(hWnd))
{
TRACE(_T("GetSafeHwnd() returned valid window handle. hWnd = %p"), hWnd);
}
else
{
TRACE(_T("GetSafeHwnd() returned INVALID window handle!"));
}
}
else
{
TRACE(_T("GetOwner() returned NULL!"));
}

CWnd* pWndSafeOwner = pWnd->GetSafeOwner();

if(pWndSafeOwner)
{
TRACE(_T("GetSafeOwner() returned valid pointer. pWndSafeOwner = %p"), pWndSafeOwner);

HWND hWnd = pWndSafeOwner->GetSafeHwnd();

if(::IsWindow(hWnd))
{
TRACE(_T("GetSafeHwnd() returned valid window handle. hWnd = %p"), hWnd);
}
else
{
TRACE(_T("GetSafeHwnd() returned INVALID window handle!"));
}
}
else
{
TRACE(_T("GetSafeOwner() returned NULL!"));
}
}

Links and references:
CWnd::SendMessage (MSDN)
CWnd::PostMessage (MSDN)

IsWindow (MSDN)
CWnd::Create (MSDN)
CWnd::CreateEx (MSDN)

Minimal Axis2C Web Service package needed for deployment with IIS

2011-10-07T19:23:00.001+01:00

If Axis2/C engine does not support OpenSSL and does not use libxml2 as XML parser, this is the minimal set of Axis2C files needed to be deployed on the machine with IIS in order to support hosting MyWebService Axis2/C Web Service:

C:\axis2c\lib\axiom.dll
C:\axis2c\lib\axis2_engine.dll
C:\axis2c\lib\axis2_http_receiver.dll
C:\axis2c\lib\axis2_http_sender.dll
C:\axis2c\lib\axis2_parser.dll
C:\axis2c\lib\axis2_xpath.dll
C:\axis2c\lib\axutil.dll
C:\axis2c\lib\guththila.dll
C:\axis2c\lib\mod_axis2_IIS.dll
C:\axis2c\lib\neethi.dll

C:\axis2c\modules\addressing
C:\axis2c\modules\addressing\axis2_mod_addr.dll
C:\axis2c\modules\addressing\module.xml

C:\axis2c\services\MyWebService\MyWebService.dll
C:\axis2c\services\MyWebService\services.xml

C:\axis2c\axis2.xml
C:\axis2c\LICENCE
C:\axis2c\NOTICE

Conditional compilation of resource file in Visual Studio

2011-10-07T18:26:00.001+01:00

How to use different resources in different build configurations, having a single resource file in project?
Answer: define different resource file preprocessor symbols for different configurations.

1. Open your project in Visual Studio 2008

2. Right click on resource script file (e.g. app.rc) and select "Properties"

3. At the top of the property page, select one platform like "Win32" or "x64".
4. In the left menu bar, select [Configuration Properties] / [Resources] / [General].

5. In the "Preprocessor Definitions" field, add "WIN32" for "Win32" platform and "WIN64" for "x64" platform. The field value will become "WINXX;_UNICODE;UNICODE". (XX will be 32 or 64)

6. Click OK to close the window.

7. Right click on resource script file (e.g. app.rc) and select "View Code".

8. In the code editor, add #ifdef and #elif to conditionally include resources when compiling. Use "WIN32" and "WIN64" preprocessor definitions that we defined just now.

Here is a sample code:
--------------------------------
#ifdef WIN32
IDB_BITMAP1 BITMAP "bitmap1.bmp"
IDB_BITMAP2 BITMAP "bitmap2.bmp"
#elif WIN64
IDR_TOOLBAR1 BITMAP "toolbar1.bmp"
IDI_ICON1 ICON "icon1.ico"
#endif
--------------------------------
9. Save the resource script file and compile the project in different platforms.

[source]

NSIS installer for 64-bit Windows

2011-10-07T16:31:00.000+01:00

Here are some tips for creating (32-bit) NSIS installer which installs 64-bit application on 64-bit Windows.

There is no 64-bit NSIS Installer (yet) so only 32-bit version will be running on 64-bit host which means that 32-bit redirection will take place: by default its Installation Directory is "C:\Program Files (x86)" and it reads/writes only from HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node portion of the registry. This is not what we want so we need to enable access to native Win64 directories/registry for our Installer.

Our installer, as 32-bit application, will probably be used both for 32-bit and 64-bit installations. It therefore needs to be able to determine architecture of the CPU it runs on. x64 plug-in offers macro RunningX64 which returns true if installer is running on 64-bit Windows (under WoW64 emulation):

setup.nsi:

!include x64.nsh
...
${If} ${RunningX64}
DetailPrint "Installer running on 64-bit host"
${EndIf}

Once we've detected 64-bit host, we need to:

set "C:\Program Files" as Installation Directory - use $PROGRAMFILES64 instead of $PROGRAMFILES
enable access to 64-bit registry - use SetRegView NSIS command

setup.nsi:

!include x64.nsh

;set initial value for $INSTDIR
InstallDir "$PROGRAMFILES\${MY_COMPANY}\${MY_APP}"
...
${If} ${RunningX64}
DetailPrint "Installer running on 64-bit host"
; disable registry redirection (enable access to 64-bit portion of registry)
SetRegView 64
; change install dir
StrCpy $INSTDIR "$PROGRAMFILES64\${BRAND_DIR}\${APOLLO_UPDATE_SERVER_DIR}"
${EndIf}

If installer needs to detect whether some 64-bit process is running, use FindProcDLL plug-in (there are couple of versions available but I found only this one - FindProcDLL_mod_by_hnedka.7z - working for me; please have a look at this forum thread). Download this archived file, unpack it and copy FindProcDLL.dll to your ..\NSIS\Plugins directory.

setup.nsi:

${If} ${RunningX64}
FindProcDLL::FindProc "Some64BitProcess.exe"
${If} $R0 == 1
DetailPrint "FindProcDLL::FindProc() returned 1 (process is running)"
${ElseIf} $R0 == 0
DetailPrint "FindProcDLL::FindProc() returned 0 (process is nor running)"
${Else}
DetailPrint "FindProcDLL::FindProc() returned unexpected value"
${Endif}
${Else}
...

How to build Axis2C for 64-bit Windows

2011-10-07T15:12:00.000+01:00

This article shows how to build Axis2/C package for 64-bit Windows (AMD64 processor architecture) from command line, by using NMAKE that comes with Visual Studio 2010. Building this package for 32-bit Windows is described here.

Step 1: Download source distribution for Windows from Apache Axis2/C Releases page. It comes as axis2c-src-1.6.0.zip file. Unzip it to some folder, e.g. "..\axis2c-src-1.6.0"

Step 2: Set NMAKE environment
..\axis2c-src-1.6.0\build\win32\makefile is Microsoft's NMAKE makefile and ..\axis2c-src-1.6.0\build\win32\configure.in is its configuration file. As I explained in the article "NMAKE and its environment", in order to compile code targeting 64-bit OS on 32-bit host NMAKE needs to use cross-compiler and linker, it needs to be able to access headers for 64-bit code, and 64-bit libraries. To achieve this we need to set environment variables in the current command prompt session which can be done in couple of ways:

run my batch file setenv.bat from the ..\axis2c-src-1.6.0\build\win32 directory providing "x64" as its argument
go to "C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64" and run vcvarsx86_amd64.bat
go to "C:\Program Files\Microsoft Visual Studio 10.0\VC" and run vcvarsall.bat providing "x86_amd64" as argument

After this, check whether nmake will use proper compiler and linker (x86_amd64 versions of cl.exe link.exe):

C:\DEVELOPMENT\Toolkits\Axis2C\axis2c-src-1.6.0\build\win32>cd "C:\Program
Files\Microsoft Visual Studio 10.0\VC"

C:\Program Files\Microsoft Visual Studio 10.0\VC>vcvarsall.bat x86_amd64
Setting environment for using Microsoft Visual Studio 2010 x64 cross tools.

C:\Program Files\Microsoft Visual Studio 10.0\VC>goto :eof

C:\Program Files\Microsoft Visual Studio 10.0\VC>cd "C:\DEVELOPMENT\Toolkits\Axi
s2C\axis2c-src-1.6.0\build\win32"

C:\DEVELOPMENT\Toolkits\Axis2C\axis2c-src-1.6.0\build\win32>where nmake
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\nmake.exe

C:\DEVELOPMENT\Toolkits\Axis2C\axis2c-src-1.6.0\build\win32>where cl
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64\cl.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\cl.exe

C:\DEVELOPMENT\Toolkits\Axis2C\axis2c-src-1.6.0\build\win32>where link
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64\link.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\link.exe

C:\DEVELOPMENT\Toolkits\Axis2C\axis2c-src-1.6.0\build\win32>

Step 3: Modify configure.in

This file contains variables and flags for conditional compiling defined in makefile. If you don't need OpenSSL support, TCP server, using libxml2 (and so zlib1 and iconv), building Apache Axis2C engine module, libcurl, then modify configure.in to be like this:

#############################################################################
### Build Details ###
#############################################################################
#
# enables https support
ENABLE_SSL = 0
#
# build libcurl transport
ENABLE_LIBCURL = 0
#
# build axis2 with Libxml2 Parser. Axis2/C will be built with embeded guththila # parser by Default.
ENABLE_LIBXML2=0
#
# build tcp server in addition to http server
WITH_TCP = 0
#
# build with archive based deployment
WITH_ARCHIVE = 0
#
#
#############################################################################
### Dependant Binary Locations (Required) ###
#############################################################################
#
# libxml2 binary location ( axis2c is built with libxml2 )
LIBXML2_BIN_DIR =
#
# iconv binary location
ICONV_BIN_DIR =
#
# zlib binary location
ZLIB_BIN_DIR=
#
#
#############################################################################
### Dependant Binary Locations (Optional) ###
#############################################################################
#
# openssl binary location
# required if ENABLE_SSL = 1
OPENSSL_BIN_DIR =
#
# libcurl binary location, only required if libcurl transport is enabled
LIBCURL_BIN_DIR =
#
#
#############################################################################
### Apache Server module (required when building Axis2/C Apache Module) ###
#############################################################################
#
# apache binary location
APACHE_BIN_DIR =
#
# apache 2 server family
# To use apache 2.2 family, use APACHE_VERSION_IS_2_0_X = 0
APACHE_VERSION_2_0_X = 0
#
#
#############################################################################
### Compiler Options ###
#############################################################################
#
# C runtime LIBRARY OPTION ( Use /MD or /MT )
CRUNTIME = /MT
#
# Embed Manifest Files
EMBED_MANIFEST = 1
#
# debug symbols
# To build with debug symbols use DEBUG = 1
DEBUG = 0

Step 4: Run NMAKE.

..\axis2c-src-1.6.0\build\win32>nmake install

Build output is in directory ..\axis2c-src-1.6.0\build\deploy:

..\axis2c-src-1.6.0\build\deploy\
bin
docs
include
lib
logs
modules
samples
services
axis2.xml
...

...and that's it! There is NO need to change any compiler/linker options in makefile. Just make sure you've set NMAKE environment properly - so x86_amd64 versions of cl.exe and link.exe are used!

You can check that all these binaries are 64-bit by using Dependency Walker.

NOTE 1: If you need to have different compiler/linker options in makefile, just add custom BUILD_X86 flag to configure.in:

# BUILD_X86 = 1 if nmake should create x86 binaries.
# BUILD_X86 = 0 if nmake should create x64 (amd) binaries.
BUILD_X86 = 0

makefile can use this file to separate compiler/linker settings for 32 and 64-bit builds (I have defined some symbols here and set /MACHINE to X64 but THAT IS NOT NECESSARY - build succeeds even without these options!):

...
...
!if "$(BUILD_X86)" == "1"
CFLAGS = /D "WIN32" /D "_WINDOWS" /D "_MBCS" /D "AXIS2_DECLARE_EXPORT" \
/D "_CRT_SECURE_NO_DEPRECATE" /D "_CRT_SECURE_NO_WARNINGS" \
/D "AXIS2_SVR_MULTI_THREADED" /W3 /wd4100 /MP10 /nologo $(AXIS2_INCLUDE_PATH) \
$(APACHE_INCLUDE_PATH)
!else
CFLAGS = /D "WIN32" /D "WIN64" /D "AMD64" /D "_WINDOWS" /D "_MBCS" /D "AXIS2_DECLARE_EXPORT" \
/D "_CRT_SECURE_NO_DEPRECATE" /D "_CRT_SECURE_NO_WARNINGS" \
/D "AXIS2_SVR_MULTI_THREADED" /W3 /wd4100 /MP10 /nologo $(AXIS2_INCLUDE_PATH) \
$(APACHE_INCLUDE_PATH)
!endif
...
...
!if "$(BUILD_X86)" == "1"
LDFLAGS = /NOLOGO /LIBPATH:$(AXIS2_LIBS) /LIBPATH:$(LIBXML2_BIN_DIR)\lib \
/LIBPATH:$(APACHE_BIN_DIR)\lib /LIBPATH:$(ZLIB_BIN_DIR)\lib
!else
LDFLAGS = /NOLOGO /LIBPATH:$(AXIS2_LIBS) /LIBPATH:$(LIBXML2_BIN_DIR)\lib \
/LIBPATH:$(APACHE_BIN_DIR)\lib /LIBPATH:$(ZLIB_BIN_DIR)\lib /MACHINE:X64
!endif

NOTE 2: If you need to build 64-bit Axis2C for deploying it as IIS module add this target to makefile:

iis_deploy: deploy axis2_core_without_server axis2_IIS_module copy_axis2_xml

and call nmake with it:

..\axis2c-src-1.6.0\build\win32>nmake iis_deploy

Your web service dll must be built for 64-bit Windows as well and must be built against 64-bit Axis2/C libraries.

Links and references:
Apache Axis2/C Installation Guide
How to: Enable a 64-Bit Visual C++ Toolset at the Command Line

32-bit and 64-bit versions of Windows C++ application

2011-10-06T19:05:00.000+01:00

How to set compiler and linker options in order to build some C++ application for 64-bit Windows? Sample application I will test this on is one that detects two things that should not be mixed:

detecting which processor architecture application has been compiled for (performed in compile time)
detecting which processor architecture application is running on (performed in run-time)

There is no portable way of performing these checks.

Compiler's target architecture can be detected by checking which pre-defined symbols (macros) have automatically been defined by compiler (this is compiler specific! - different compilers use different macros). Some Microsoft-specific are:

_WIN32 - defined for applications for Win32 and Win64. Always defined.
_WIN64 - defined for applications for Win64.
_M_AMD64 - defined for x64 processors
_M_X64 - defined for x64 processors
_M_IX86 - defined for x86 processors
_M_IA64 - defined for Itanium Processor Family 64-bit processors

These macros determine target processor - one that we are building application for (not processor we are building on). We don't need to add them manually as compiler will define them: _WIN32 and _M_IX86 for 32-bit applications and _WIN64, _M_AMD64, _M_X64 and _M_IA64 for 64-bit ones.

Another test can be checking the value of the sizeof(void*). It is 4 bytes in applications compiled for 32-bit architectures and 8 bytes in 64-bit applications, regardless on the processor architecture application is running on.

Host's processor architecture can be obtained in run-time in various ways, of which some of them (on Windows) are:

__cpuid
check PROCESSOR_ARCHITECTURE and PROCESSOR_ARCHITEW6432 environment variables (or read value of PROCESSOR_ARCHITECTURE in registry on path HKLM\SYSTEM\CurrentControlSet\Control\Session Manager\Environment)
Use GetSystemInfo() or GetNativeSystemInfo()

main.cpp uses methods described above:

#include <windows.h>
#include <iostream>
#include <string>
#include <intrin.h>
using namespace std;

void CheckIs64BitAvailable()
{
bool b64Available = false;
int CPUInfo[4] = {0};
__cpuid(CPUInfo, 0);
b64Available = (CPUInfo[3] & 0x20000000) || false;

if(b64Available)
{
cout << "64-bit processor" << endl;
}
else
{
cout << "32-bit processor" << endl;
}
}

void CheckNativeSystemProcessorArchitecture()
{
SYSTEM_INFO si;
memset(&si, 0, sizeof(si));
GetNativeSystemInfo(&si);

switch(si.wProcessorArchitecture)
{
case PROCESSOR_ARCHITECTURE_AMD64:
cout << "PROCESSOR_ARCHITECTURE_AMD64 - x64 (AMD or Intel)" << endl;
break;
case PROCESSOR_ARCHITECTURE_IA64:
cout << "PROCESSOR_ARCHITECTURE_IA64 - Intel Itanium-based" << endl;
break;
case PROCESSOR_ARCHITECTURE_INTEL:
cout << "PROCESSOR_ARCHITECTURE_INTEL - x86" << endl;
break;
case PROCESSOR_ARCHITECTURE_UNKNOWN:
cout << "PROCESSOR_ARCHITECTURE_UNKNOWN - Unknown architecture" << endl;
break;
}
}

void CheckSystemProcessorArchitecture()
{
cout << "Calling GetSystemInfo()..." << endl;

SYSTEM_INFO si;
memset(&si, 0, sizeof(si));
GetSystemInfo(&si);

switch(si.wProcessorArchitecture)
{
case PROCESSOR_ARCHITECTURE_AMD64:
cout << "PROCESSOR_ARCHITECTURE_AMD64 - x64 (AMD or Intel)" << endl;
break;
case PROCESSOR_ARCHITECTURE_IA64:
cout << "PROCESSOR_ARCHITECTURE_IA64 - Intel Itanium-based" << endl;
break;
case PROCESSOR_ARCHITECTURE_INTEL:
cout << "PROCESSOR_ARCHITECTURE_INTEL - x86" << endl;
break;
case PROCESSOR_ARCHITECTURE_UNKNOWN:
cout << "PROCESSOR_ARCHITECTURE_UNKNOWN - Unknown architecture" << endl;
break;
}
}

void CheckEnvVariable_PROCESSOR_ARCHITECTURE()
{
char* pszProcArch = getenv("PROCESSOR_ARCHITECTURE");
if(pszProcArch)
{
cout << "PROCESSOR_ARCHITECTURE (environment variable): " << string(pszProcArch) << endl;
}
else
{
cout << "PROCESSOR_ARCHITECTURE (environment variable) not found" << endl;
}
}

void CheckEnvVariable_PROCESSOR_ARCHITEW6432()
{
// PROCESSOR_ARCHITEW6432 is defined only in WoW64 where reports the original native processor architecture
char* pszProcArch = getenv("PROCESSOR_ARCHITEW6432");
if(pszProcArch)
{
cout << "PROCESSOR_ARCHITEW6432 (environment variable): " << string(pszProcArch) << endl;
}
else
{
cout << "PROCESSOR_ARCHITEW6432 (environment variable) not found" << endl;
}
}

void CheckRegVal_PROCESSOR_ARCHITECTURE()
{
HKEY hKey;
DWORD dwBuffSize = 1023;
DWORD dwType;
char szValue[1024] = {0};

LONG lErrorCode = RegOpenKeyEx(
HKEY_LOCAL_MACHINE,
"SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment",
0,
KEY_QUERY_VALUE,
&hKey);

if(lErrorCode!= ERROR_SUCCESS)
{
cout << "RegOpenKeyEx() failed. Error: " << lErrorCode << endl;
return;
}

RegQueryValueEx(
hKey,
"PROCESSOR_ARCHITECTURE",
NULL,
&dwType,
(LPBYTE)szValue,
&dwBuffSize);

cout << "PROCESSOR_ARCHITECTURE (registry value): " << string(szValue) << endl;

RegCloseKey(hKey);
}

int main()
{
cout << "sizeof(void*) = " << sizeof(void*) << " [bytes]"<< endl;

CheckIs64BitAvailable();
CheckRegVal_PROCESSOR_ARCHITECTURE();

// Defined for applications for Win32 and Win64. Always defined.
#ifdef _WIN32
cout << "_WIN32 defined" << endl;
#endif

// _WIN64 is defined for applications for Win64 (they can run only on Win64)
#ifdef _WIN64
cout << "_WIN64 defined => target architecture is Win64; Process is running on native Win64" << endl;
CheckSystemProcessorArchitecture();
CheckEnvVariable_PROCESSOR_ARCHITECTURE();
#else
cout << "_WIN64 is not defined => target architecture is Win32" << endl;

BOOL bIs64 = FALSE;
IsWow64Process(GetCurrentProcess(), &bIs64);

if(bIs64)
{
cout << "Process is running under WoW64" << endl;
CheckNativeSystemProcessorArchitecture();
CheckEnvVariable_PROCESSOR_ARCHITEW6432();
}
else
{
cout << "Process is running on Win32" << endl;
CheckSystemProcessorArchitecture();
CheckEnvVariable_PROCESSOR_ARCHITECTURE();
}
#endif

// WIN32 is defined outside compiler - by the SDK or the build environment
#ifdef WIN32
cout << "WIN32 defined" << endl;
#endif

// WIN64 is defined outside compiler - by the SDK or the build environment
#ifdef WIN64
cout << "WIN64 defined" << endl;
#endif

// Pre-defined Architecture Macro: Intel x86; Defined for x86 processors
#ifdef _M_IX86
cout << "_M_IX86 defined: " << _M_IX86 << endl;
#endif

// Pre-defined Architecture Macro: AMD64; Defined for x64 processors.
#ifdef _M_X64
cout << "_M_X64 defined: " << _M_X64 << endl;
#endif

// Defined for x64 processors.
#ifdef _M_AMD64
cout << "_M_AMD64 defined: " << _M_AMD64 << endl;
#endif

// Pre-defined Architecture Macro: Intel Architecture-64 (Defined for Itanium Processor Family 64-bit processors.)
#ifdef _M_IA64
cout << "_M_IA64 defined: " << _M_IA64 << endl;
#endif

return 0;
}

This is application's output when run on 32-bit Windows (Win 7):

..\Release>ProcArchTest_x86.exe
sizeof(void*) = 4 [bytes]
32-bit processor
PROCESSOR_ARCHITECTURE (registry value): x86
_WIN32 defined
_WIN64 is not defined => target architecture is Win32
Process is running on Win32
Calling GetSystemInfo()...
PROCESSOR_ARCHITECTURE_INTEL - x86
PROCESSOR_ARCHITECTURE (environment variable): x86
WIN32 defined
_M_IX86 defined: 600

C:\DEVELOPMENT\RESEARCH\C++\ProcessorBitTest\Release>

This is application's output when run on 64-bit Windows (Win 7 emulated on VirtualBox):

C:\Users\Bojan\Desktop>ProcArchTest_x86.exe
sizeof(void*) = 4 [bytes]
32-bit processor
PROCESSOR_ARCHITECTURE (registry value): AMD64
_WIN32 defined
_WIN64 is not defined => target architecture is Win32
Process is running under WoW64
PROCESSOR_ARCHITECTURE_AMD64 - x64 (AMD or Intel)
PROCESSOR_ARCHITEW6432 (environment variable): AMD64
WIN32 defined
_M_IX86 defined: 600

C:\Users\Bojan\Desktop>

Now, let us build this application for 64-bit Windows. In Visual Studio, we need to create a new build platform: Build -> Configuration Manager -> Active Solution Platform, New; select "x64" and copy settings from Win32.

Let us compare compiler options for 32-bit and 64-bit Release configurations in order to see what are the differences:

Compiler options for Win32 Release:

/Zi /nologo /W3 /WX- /O2 /Oi /Oy- /GL /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /Gm- /EHsc /MT /GS /Gy /fp:precise /Zc:wchar_t /Zc:forScope /Fp"Release\ProcArchTest_x86.pch" /Fa"Release\" /Fo"Release\" /Fd"Release\vc100.pdb" /Gd /analyze- /errorReport:queue

Compiler options for x64 Release:

/Zi /nologo /W3 /WX- /O2 /Oi /GL /D "WIN32" /D "NDEBUG" /D "_CONSOLE" /Gm- /EHsc /MT /GS /Gy /fp:precise /Zc:wchar_t /Zc:forScope /Fp"x64\Release\ProcArchTest_x64.pch" /Fa"x64\Release\" /Fo"x64\Release\" /Fd"x64\Release\vc100.pdb" /Gd /errorReport:queue

We can see that all options are the same except in case of /Oy and /analyze which are available only for x86 compilers.

What about linker options?

Linker options for Win32 Release:

/OUT:"..\Release\ProcArchTest_x86.exe" /INCREMENTAL:NO /NOLOGO "kernel32.lib" "user32.lib" "gdi32.lib" "winspool.lib" "comdlg32.lib" "advapi32.lib" "shell32.lib" "ole32.lib" "oleaut32.lib" "uuid.lib" "odbc32.lib" "odbccp32.lib" /MANIFEST /ManifestFile:"Release\ProcArchTest_x86.exe.intermediate.manifest" /ALLOWISOLATION /MANIFESTUAC:"level='asInvoker' uiAccess='false'" /DEBUG /PDB:"..\ProcessorBitTest\Release\ProcArchTest_x86.pdb" /SUBSYSTEM:CONSOLE /OPT:REF /OPT:ICF /PGD:"..\ProcessorBitTest\Release\ProcArchTest_x86.pgd" /LTCG /TLBID:1 /DYNAMICBASE /NXCOMPAT /MACHINE:X86 /ERRORREPORT:QUEUE

Linker options for x64 Release:

/OUT:"..\x64\Release\ProcArchTest_x64.exe" /INCREMENTAL:NO /NOLOGO "kernel32.lib" "user32.lib" "gdi32.lib" "winspool.lib" "comdlg32.lib" "advapi32.lib" "shell32.lib" "ole32.lib" "oleaut32.lib" "uuid.lib" "odbc32.lib" "odbccp32.lib" /MANIFEST /ManifestFile:"x64\Release\ProcArchTest_x64.exe.intermediate.manifest" /ALLOWISOLATION /MANIFESTUAC:"level='asInvoker' uiAccess='false'" /DEBUG /PDB:"..\ProcessorBitTest\x64\Release\ProcArchTest_x64.pdb" /SUBSYSTEM:CONSOLE /OPT:REF /OPT:ICF /PGD:"..\ProcessorBitTest\x64\Release\ProcArchTest_x64.pgd" /LTCG /TLBID:1 /DYNAMICBASE /NXCOMPAT /MACHINE:X64 /ERRORREPORT:QUEUE

We can see that linker options differ only in the value of /MACHINE option.

NOTE: /MACHINE option does not need to be set at all! Compiler inserts information about target architecture in OBJ files' headers. OBJ files created with Microsoft compiler have PE/COFF format which is described in Microsoft PE and COFF Specification. At the beginning of an object file, or immediately after the signature of an image file, is a standard COFF file header. Its first field is "Machine" whose value is the number that identifies the type of target machine (CPU type). Some values are: IMAGE_FILE_MACHINE_AMD64 (x64), IMAGE_FILE_MACHINE_I386 (Intel 386 or later processors and compatible processors - x86), IMAGE_FILE_MACHINE_IA64 (Intel Itanium processor family). Linker reads that information. If you compile your app with $(VCInstallDir)bin\x86_amd64\cl.exe linker will create amd64 binary even with /MACHINE Not Set! Cross-compiling with Microsoft (Visual Studio) tools is all about using correct compiler and linker! Compiler and linker options can actually be same for both 32-bit and 64-bit builds! When building 64-bit application in Visual Studio, just make sure that Executable Directories has (cl.exe and link.exe) paths in this order $(VCInstallDir)bin\x86_amd64;$(VCInstallDir)bin; and that AMD paths are listed first in Include and Library Directories (but all this should be done automatically upon creation of x64 project!).

Let us continue with analysis.

Although names of some libraries end with "32" for both x86 and x64 configurations, their different (32-bit or 64-bit) versions are actually used in different builds. Same for the compiler and linker - please read my article "NMAKE and its environment".

Let us try to run now our 64-bit application on 32-bit Windows OS:

..\x64\Release>ProcArchTest_x64.exe
This version of ..\x64\Release\ProcArchTest_x64.exe is not compatible with the
version of Windows you're running. Check your computer's system information
to see whether you need a x86 (32-bit) or x64 (64-bit) version of the program,
and then contact the software publisher.

C:\DEVELOPMENT\RESEARCH\C++\ProcessorBitTest\x64\Release>

This was expected as 64-bit application cannot run on 32-bit operating systems.
What about running it in its natural, 64-bit, enviroment - on 64-bit OS?

C:\Users\Bojan\Desktop>ProcArchTest_x64.exe
sizeof(void*) = 8 [bytes]
32-bit processor
PROCESSOR_ARCHITECTURE (registry value): AMD64
_WIN32 defined
_WIN64 defined => target architecture is Win64; Process is running on native Win
64
Calling GetSystemInfo()...
PROCESSOR_ARCHITECTURE_AMD64 - x64 (AMD or Intel)
PROCESSOR_ARCHITECTURE (environment variable): AMD64
WIN32 defined
_M_X64 defined: 100
_M_AMD64 defined: 100

C:\Users\Bojan\Desktop>

Conclusion:

application targets 64-bit architecture if _WIN64, _M_X64 and/or _M_AMD64 are defined and/or if sizeof(void*) is 8
reliable way of getting the architecture of the host processor in runtime is reading PROCESSOR_ARCHITECTURE value from registry or using GetSystemInfo()/GetNativeSystemInfo()

Advice:
Don't rely on WoW64 as it might not be enabled/installed on the target machine (e.g. WoW64 is optional on Windows Server 2003 R2). WoW64 is intended to support legacy 32-bit applications anyway. Build new applications for both x86 and x64 architectures. This way you can avoid some potential errors in applications that can occur due to directory and registry redirections under WoW64.

Links and references:

IsWow64Process function
64-bit (Wikipedia)
WoW64 (Wikipedia)
Use Visual Studio to build 64-bit application (MSDN blog)
Everything You Need To Know To Start Programming 64-Bit Windows Systems
Visual Studio Development Environment 64-Bit Support
HOWTO: Detect Process Bitness How to: Configure Projects to Target Platforms (MSDN)
How to: Configure Visual C++ Projects to Target 64-Bit Platforms (MSDN)
How to determine whether a computer is running a 32-bit version or 64-bit version of the Windows operating system (MSDN)
Predefined Macros (MSDN)

You already know what your target architecture is (or at least you should)
How to detect programmatically whether you are running on 64-bit Windows
Detecting CPU architecture compile-time
Detect system architecture (x86/x64) while running
#ifdef for 32-bit platform
Determining 64-bit vs. 32-bit Windows

Use Visual Studio to build 64-bit application
Seven Steps of Migrating a Program to a 64-bit System

How to use nmake and makefile

2011-10-05T17:21:00.000+01:00

Let's build simple "Hello, world!" application from command line by using Microsoft's nmake. Necessary steps are:

1) create project directory ("..\HelloWorld")
2) create source file ("..\HelloWorld\main.cpp")
3) create makefile ("..\HelloWorld\makefile")
4) set up environment (environment variables) for nmake. I will use my setenv.bat script from my post "NMAKE and its environment" (run "..\HelloWorld\setenv.bat" with "x86" argument)
5) run nmake

main.cpp:

#include <iostream>
int main()
{
std::cout << "Hello, world!" << std::endl;
return 0;
}

The shortest version of makefile needs to contain at least one description block:

target : dependencies
commands

makefile:

foo: main.cpp
cl main.cpp

Here's the order of commands in the command prompt window:

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>setenv x86
Setting environment for using Microsoft Visual Studio 2010 x86 tools.

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>where nmake
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\nmake.exe

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>where cl.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\cl.exe

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>where link.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\link.exe

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>nmake

Microsoft (R) Program Maintenance Utility Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

cl main.cpp
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 16.00.30319.01 for 80x86
Copyright (C) Microsoft Corporation. All rights reserved.

main.cpp
c:\Program Files\Microsoft Visual Studio 10.0\VC\include\xlocale(323) : warning
C4530: C++ exception handler used, but unwind semantics are not enabled. Specify
/EHsc
Microsoft (R) Incremental Linker Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

/out:main.exe
main.obj

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>main
Hello, world!

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld>

Compiler creates obj file and automatically invokes the linker after compiling unless the /c option is used. Linker creates executable. Upon nmake call, we have following files in our project directory:

..\HelloWorld\main.cpp
main.exe
main.obj
makefile
setenv.bat

Ok, we got binary but let us tidy things a bit and let us see how to involve header files. By default, compiler gives binary a default name using the base name of the first source or object file specified on the command line. I want binary to be named as "helloworld.exe" and want it to be placed in "..\HelloWorld\bin\x86" directory. OBJ files should be put in the intermediate directory "..\HelloWorld\intermediate\x86". I want my main function to be in "..\HelloWorld\src\main.cpp" and to use some function declared in header "..\HelloWorld\include\printx.h" and defined in "..\HelloWorld\src\printx.cpp". Furthermore, makefile should be in "..\HelloWorld\build". Project structure before nmake call should be:

..\HelloWorld\src\main.cpp
..\HelloWorld\src\printx.cpp
..\HelloWorld\include\printx.h
..\HelloWorld\build\makefile
..\HelloWorld\build\setenv.bat

And after nmake call:

..\HelloWorld\src\main.cpp
..\HelloWorld\src\printx.cpp
..\HelloWorld\include\printx.h
..\HelloWorld\build\makefile
..\HelloWorld\build\setenv.bat
..\HelloWorld\intermediate\x86\main.obj
..\HelloWorld\intermediate\x86\printx.obj
..\HelloWorld\bin\x86\helloworld.exe

Let us assume that new unit in our project, printx, contains implementation of our custom manipulator which inserts given number of asterisks into output stream.

printx.h:

#ifndef _PRINTX_H_
#define _PRINTX_H_
#include <iomanip>

// helper function which appends an array of asterisks to ostream
void append_asterisks(std::ios_base& os, int nCount);

// custom manipulator, based on std::_Smanip macro
std::_Smanip __cdecl insert_asterisks(int nCount);
#endif //_PRINTX_H_

printx.cpp:

#include "printx.h"

void append_asterisks(std::ios_base& os, int nCount)
{
std::ostream* pos = dynamic_cast <std::ostream*>(&os);

if(pos)
{
for(int i = 0; i < nCount; i++)
(*pos) << '*';
};
}

std::_Smanip<int> __cdecl insert_asterisks(int no)
{
return (std::_Smanip<int>(&append_asterisks, no));
}

We are using this function in our main:
main.cpp:

#include <iostream>
#include "printx.h"

int main()
{
std::cout << insert_asterisks(10) << "Hello, world!" << insert_asterisks(10) << std::endl;
return 0;
}

New makefile uses following compiler options:
/EHsc - to suppress previous compiler warning related to exceptions handling
/Fe - to define binary output destination directory
/I - to provide path to header file(s)

It contains pseudo-targets which operate on directory structure ("create_dirs", "clean") and one that groups all actions into a single command ("all").

makefile:

#define macros
EXECUTABLE_NAME = helloworld.exe
DIR_SRC = ..\src
DIR_INCLUDE = ..\include
DIR_BIN = ..\bin
DIR_BIN_X86 = $(DIR_BIN)\x86
DIR_INTERMEDIATE = ..\intermediate
DIR_INTERMEDIATE_X86 = $(DIR_INTERMEDIATE)\x86

SRC_FILES= \
$(DIR_SRC)\main.cpp \
$(DIR_SRC)\printx.cpp

# description block
$(EXECUTABLE_NAME) : $(SRC_FILES)
cl /EHsc /Fe$(DIR_BIN_X86)\$(EXECUTABLE_NAME) /I$(DIR_INCLUDE) $(SRC_FILES)
copy *.obj $(DIR_INTERMEDIATE_X86)
del *.obj

# build application
helloworld: $(EXECUTABLE_NAME)

# create output directories
create_dirs:
@if not exist $(DIR_BIN_X86) mkdir $(DIR_BIN_X86)
@if not exist $(DIR_INTERMEDIATE_X86) mkdir $(DIR_INTERMEDIATE_X86)

# delete output directories
clean:
@if exist $(DIR_BIN) rmdir /S /Q $(DIR_BIN)
@if exist $(DIR_INTERMEDIATE) rmdir /S /Q $(DIR_INTERMEDIATE)

# create directories and build application
all: clean create_dirs helloworld

Here's the order of commands in the command prompt window:

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\build>nmake all

Microsoft (R) Program Maintenance Utility Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

cl /EHsc /Fe..\bin\x86\helloworld.exe /I..\include ..\src\main.cpp ..\s
rc\printx.cpp
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 16.00.30319.01 for 80x86
Copyright (C) Microsoft Corporation. All rights reserved.

main.cpp
printx.cpp
Generating Code...
Microsoft (R) Incremental Linker Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

/out:..\bin\x86\helloworld.exe
main.obj
printx.obj
copy *.obj ..\intermediate\x86
main.obj
printx.obj
2 file(s) copied.
del *.obj

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\build>cd "..\bin\x86"

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\bin\x86>helloworld.exe
**********Hello, world!**********

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\bin\x86>

We can separate compiling from linking in two steps - compiling source files into object files and linking object files into executable.

makefile:

#define macros
EXECUTABLE_NAME = helloworld.exe
DIR_SRC = ..\src
DIR_INCLUDE = ..\include
DIR_BIN = ..\bin
DIR_BIN_X86 = $(DIR_BIN)\x86
DIR_INTERMEDIATE = ..\intermediate
DIR_INTERMEDIATE_X86 = $(DIR_INTERMEDIATE)\x86

OBJ_FILES = \
$(DIR_INTERMEDIATE_X86)\main.obj \
$(DIR_INTERMEDIATE_X86)\printx.obj

$(DIR_INTERMEDIATE_X86)\main.obj: $(DIR_SRC)\main.cpp
cl /c /EHsc /Fe$(DIR_INTERMEDIATE_X86)\main.obj /I$(DIR_INCLUDE) $(DIR_SRC)\main.cpp
copy main.obj $(DIR_INTERMEDIATE_X86)
del main.obj

$(DIR_INTERMEDIATE_X86)\printx.obj: $(DIR_SRC)\printx.cpp
cl /c /EHsc /Fe$(DIR_INTERMEDIATE_X86)\printx.obj /I$(DIR_INCLUDE) $(DIR_SRC)\printx.cpp
copy printx.obj $(DIR_INTERMEDIATE_X86)
del printx.obj

$(EXECUTABLE_NAME) : $(OBJ_FILES)
link /out:$(DIR_BIN_X86)\$(EXECUTABLE_NAME) $(OBJ_FILES)

# build application
helloworld: $(EXECUTABLE_NAME)

# create output directories
create_dirs:
@if not exist $(DIR_BIN_X86) mkdir $(DIR_BIN_X86)
@if not exist $(DIR_INTERMEDIATE_X86) mkdir $(DIR_INTERMEDIATE_X86)

# delete output directories
clean:
@if exist $(DIR_BIN) rmdir /S /Q $(DIR_BIN)
@if exist $(DIR_INTERMEDIATE) rmdir /S /Q $(DIR_INTERMEDIATE)

# create directories and build application
all: clean create_dirs helloworld

We can avoid repeating description blocks for each OBJ file by using inference rules. They are generic description blocks that define rules of how files with one extension are converted into files with the same name but different extensions. These rules are applied when resolving dependants. In the following makefile, EXE depends on OBJ files and inference rule defines how are OBJ files generated from CPP files:

makefile:

#define macros
EXECUTABLE_NAME = helloworld.exe
DIR_SRC = ..\src
DIR_INCLUDE = ..\include
DIR_BIN = ..\bin
DIR_BIN_X86 = $(DIR_BIN)\x86
DIR_INTERMEDIATE = ..\intermediate
DIR_INTERMEDIATE_X86 = $(DIR_INTERMEDIATE)\x86

SRC_FILES= \
$(DIR_SRC)\main.cpp \
$(DIR_SRC)\printx.cpp

{$(DIR_SRC)}.cpp{$(DIR_INTERMEDIATE_X86)}.obj ::
@echo Compiling...
cl /c /EHsc /Fo$(DIR_INTERMEDIATE_X86)\ /I$(DIR_INCLUDE) $<

$(EXECUTABLE_NAME) : $(DIR_INTERMEDIATE_X86)\*.obj
@echo Linking $(EXECUTABLE_NAME)...
link /out:$(DIR_BIN_X86)\$(EXECUTABLE_NAME) $(DIR_INTERMEDIATE_X86)\*.obj

# build application
helloworld: $(EXECUTABLE_NAME)

# create output directories
create_dirs:
@if not exist $(DIR_BIN_X86) mkdir $(DIR_BIN_X86)
@if not exist $(DIR_INTERMEDIATE_X86) mkdir $(DIR_INTERMEDIATE_X86)

# delete output directories
clean:
@if exist $(DIR_BIN) rmdir /S /Q $(DIR_BIN)
@if exist $(DIR_INTERMEDIATE) rmdir /S /Q $(DIR_INTERMEDIATE)

# create directories and build application
all: clean create_dirs helloworld

Here is the order of commands in the command prompt window:

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\build>nmake all

Microsoft (R) Program Maintenance Utility Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

Compiling...
cl /c /EHsc /Fo..\intermediate\x86\ /I..\include ..\src\*.cpp
Microsoft (R) 32-bit C/C++ Optimizing Compiler Version 16.00.30319.01 for 80x86
Copyright (C) Microsoft Corporation. All rights reserved.

main.cpp
printx.cpp
Generating Code...
Linking helloworld.exe...
link /out:..\bin\x86\helloworld.exe ..\intermediate\x86\*.obj
Microsoft (R) Incremental Linker Version 10.00.30319.01
Copyright (C) Microsoft Corporation. All rights reserved.

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\build>cd "..\bin\x86"

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\bin\x86>helloworld.exe
**********Hello, world!**********

C:\DEVELOPMENT\RESEARCH\C++\HelloWorld\bin\x86>

Links and references:
Make (software) (Wikipedia)
NMAKE Reference (MSDN)
C/C++ Building Reference (MSDN)
Example Demonstrates Using Paths in NMAKE (MSDN)
MS C/C++: The nmake Command
The Makefile
Using Nmake
Nmake Makefile Tutorial and Example
Makefile.msvc (makefile example)
Building a simple OpenGL application
NMAKE (course; pdf)
Managing Projects with NMAKE
The make utility

NMAKE and its environment

2011-10-03T18:35:00.000+01:00

nmake is a Microsoft's command-line tool for building C/C++ applications. nmake comes with Visual Studio and Windows Driver Development Kit (DDK) and it comes in two versions: one for building 32-bit and another for building 64-bit binaries. Here is the list of its locations, depending on which Microsoft product is installed on your machine:

Visual Studio 2010:

C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\nmake.exe
(32-bit binary; depends on 32-bit advapi32.dll, kernel32.dll and msvcr100.dll)

C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\amd64\nmake.exe
(64-bit binary; depends on 64-bit advapi32.dll, kernel32.dll and msvcr100.dll)

Visual Studio 2008:

C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\nmake.exe
(32-bit binary; depends on 32-bit advapi32.dll, kernel32.dll and msvcr90.dll)

C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\amd64\nmake.exe
(64-bit binary; depends on 64-bit advapi32.dll, kernel32.dll and msvcr90.dll)

Windows DDK (I have some pretty old installed on my machine):

C:\WinDDK\6001.18001\bin\x86\nmake.exe
(32-bit binary; depends on 32-bit advapi32.dll, kernel32.dll and msvcr80.dll)

C:\WinDDK\6001.18001\bin\ia64\nmake.exe
(64-bit binary; depends on 64-bit advapi32.dll, kernel32.dll and msvcr80.dll)

Binaries from amd64/ia64 directories are 64-bit and cannot be run on 32-bit machines.

msvcrXX.dll is Microsoft Visual C Runtime library. XX is its version, specific for each version of Visual Studio: 80 for VS2005, 90 for VS2008 and 100 for VS2010. Binary linked against some msvcr library requires existence of that library on the machine it runs on. If it does not exist, it can be installed with Microsoft Visual C++ VS20XX Redistributable Package (x86 or x64).

If you want to run some particular nmake on your machine, make sure its path is listed in Paths environment variable. If there are more versions of nmake present on your machine, put path to desired version before paths to the other versions. E.g. put path "C:\Program Files\Microsoft Visual Studio 10.0\VC\bin" before "C:\Program Files\Microsoft Visual Studio 9.0\VC\bin" in Paths if you want to run VS2010 nmake. You can always check which nmake will be called from some arbitrary location if executing (from a command line):

where nmake

If nmake resides in multiple directories, all those directories will be listed but only instance from the first listed will be called,
nmake reads instructions from a file called makefile (full name of this file usually does not contain a dot and extension). Instructions of how to build a specific binary (or binaries) are grouped into named targets. Those instructions contain compiler and linker calls, provided with source files, paths to headers, dependencies, object file names and compiler and linker options. Tags for groups of targets or sets of instructions that don't make binaries (like creating or deleting files or directories) are pseudo-targets.

You need to provide target or pseudo-target name when calling nmake. You can provide path to makefile; without it nmake looks for it in the current directory.

makefile contains instruction to call Microsoft compiler, cl.exe and linker, link.exe. Just like nmake, they come with Visual Studio and Windows DDK.

Visual Studio 2010:

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\amd64\cl.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\amd64\link.exe
(64-bit compiler and linker for AMD64 architecture)

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\cl.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\link.exe
(32-bit compiler and linker for building 32-bit applications)

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64\cl.exe
(depends on advapi32.dll, kernel32.dll, msvcr100.dll, version.dll, psapi.dll and shell32.dll from C:\Windows\System32 and mspdb100.dll from c:\program files\microsoft visual studio 10.0\common7\ide)

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64\link.exe
(depends on advapi32.dll, kernel32.dll, msvcr100.dll, psapi.dll and user32.dll from C:\Windows\System32 and mspdb100.dll from c:\program files\microsoft visual studio 10.0\common7\ide) (32-bit cross-compiler and linker for building 64-bit applications for AMD64 architectures)

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_ia64\cl.exe
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_ia64\link.exe
(32-bit cross-compiler and linker for building 64-bit applications for Itanium architectures)

Visual Studio 2008:

c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\amd64\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\amd64\link.exe

c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\link.exe

c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\x86_amd64\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\bin\x86_amd64\link.exe

c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_arm\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_arm\link.exe

c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_mips\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_mips\link.exe

c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_sh\cl.exe
c:\Program Files\Microsoft Visual Studio 9.0\VC\ce\bin\x86_sh\link.exe

Windows DDK:

c:\WinDDK\6001.18001\bin\ia64\ia64\cl.exe
c:\WinDDK\6001.18001\bin\ia64\ia64\link.exe
c:\WinDDK\6001.18001\bin\x86\amd64\cl.exe
c:\WinDDK\6001.18001\bin\x86\amd64\link.exe
c:\WinDDK\6001.18001\bin\x86\ia64\cl.exe
c:\WinDDK\6001.18001\bin\x86\ia64\link.exe
c:\WinDDK\6001.18001\bin\x86\x86\cl.exe
c:\WinDDK\6001.18001\bin\x86\x86\link.exe

Again, which compiler and linker will be called depends on paths listed in Path environment variable. Paths used can be checked by calling (from a command line):

where cl.exe
where link.exe

For example, if we want to build some 64-bit application for AMD architecture (which is usually named x64 and is more common than Itanium one) and we we want to build it on 32-bit machine, using VS2010, we need to use cross-compiler and so will add following paths to Path environment variable:

C:\Windows\System32; (path to dlls used by cl.exe and link.exe)
c:\program files\microsoft visual studio 10.0\common7\ide; (path to dlls used by cl.exe and link.exe)
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64; (path to cl.exe and link.exe)
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin; (path to nmake.exe)

If you try to run 64-bit compiler on 32-bit machine, you'll get message:

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\amd64>cl.exe /?
This version of c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\amd64\cl.ex
e is not compatible with the version of Windows you're running. Check your compu
ter's system information to see whether you need a x86 (32-bit) or x64 (64-bit)
version of the program, and then contact the software publisher.

You can run 32-bit compiler or 32-bit cross-compiler on 32-bit machine only:

c:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64>cl.exe /?
Microsoft (R) C/C++ Optimizing Compiler Version 16.00.30319.01 for x64
Copyright (C) Microsoft Corporation. All rights reserved.

This is not enough for nmake build to be successful. Compiler reads paths to Visual C++ and Windows SDK (Windows Framework) headers from INCLUDE environment variable. These headers are coming with each version of Visual Studio and we need to make sure cl.exe will be using correct ones. For example, if we want to use VS2010, we will set INCLUDE as:

c:\Program Files\Microsoft Visual Studio 10.0\VC\include; (Visual C++ headers - part of Microsoft's implementation of C++ standard)
c:\Program Files\Microsoft Visual Studio 10.0\VC\atlmfc\include; (ATL/MFC headers - add this path only for this type of applications)
c:\Program Files\Microsoft SDKs\Windows\v7.0A\include; (Windows SDK headers)

Furthermore, linker reads paths to Visual C++ and Windows Framework libraries from LIB environment variable. These libraries are specific for each version of Visual Studio and target architecture. If using VS2010 and building binary for AMD64 architecture, we would set LIB as:

c:\Program Files\Microsoft Visual Studio 10.0\VC\lib\amd64; (Visual C++ libraries)
c:\Program Files\Microsoft Visual Studio 10.0\VC\atlmfc\lib\amd64; (ATL/MFC libraries- add this path only for this type of applications)
c:\Program Files\Microsoft SDKs\Windows\v7.0A\lib\x64; (Windows SDK libraries)

Of course, if your application depends on some other framework or package, INCLUDE needs to contain path to its headers and LIB path to its libraries.

I wrote one short batch file for setting Visual Studio environment (environmental variables) for x86 or x64 builds:
setenv.bat (caret character is used to break long lines):

@rem B.Komazec Setting environment for using Microsoft Visual Studio 2010 x86/x64 tools.
@echo off

@if "%1"=="x86" goto set_x86
@if "%1"=="x64" goto set_x64
@if "%1"=="" goto error

:set_x86
@echo Setting environment for using Microsoft Visual Studio 2010 x86 tools.

set INCLUDE=^
c:\Program Files\Microsoft Visual Studio 10.0\VC\include;^
c:\Program Files\Microsoft SDKs\Windows\v7.0A\include;

set LIB=^
c:\Program Files\Microsoft Visual Studio 10.0\VC\lib;^
c:\Program Files\Microsoft SDKs\Windows\v7.0A\lib;

set PATH=^
%SystemRoot%\system32;^
c:\Program Files\Microsoft Visual Studio 10.0\VC\bin;^
c:\program files\microsoft visual studio 10.0\common7\ide;

goto test_bin_locations

:set_x64
@echo Setting environment for using Microsoft Visual Studio 2010 x64 tools.

set INCLUDE=^
c:\Program Files\Microsoft Visual Studio 10.0\VC\include;^
c:\Program Files\Microsoft SDKs\Windows\v7.0A\include;

set LIB=^
c:\Program Files\Microsoft Visual Studio 10.0\VC\lib\amd64;^
c:\Program Files\Microsoft SDKs\Windows\v7.0A\lib\x64;

set PATH=^
%SystemRoot%\system32;^
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64;^
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin;^
C:\Program Files\Microsoft Visual Studio 10.0\Common7\ide;

goto test_bin_locations

:test_bin_locations
@echo on
where nmake
where cl.exe
where link.exe
@echo off
goto:eof

:error
@echo Usage: setenv.bat [x86^|x64]

goto:eof

For example, to set environment for building x64 (AMD64) application with VS2010, call this script providing "x64" as an argument:

setenv x64

Note that changes made with SET will remain only for the duration of the current CMD session. To check the value of some environment variable in command prompt window use ECHO command followed by environment variable surrounded with percent signs:

echo %Path%

You can also use batch files that come with Visual Studio:
Visual Studio 2010:

C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\vcvars32.bat
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_amd64\vcvarsx86_amd64.bat
C:\Program Files\Microsoft Visual Studio 10.0\VC\bin\x86_ia64\vcvarsx86_ia64.bat
C:\Program Files\Microsoft Visual Studio 10.0\VC\vcvarsall.bat

Visual Studio 2008:

C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat
C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\vcvars32.bat
C:\Program Files\Microsoft Visual Studio 9.0\VC\bin\x86_amd64\vcvarsx86_amd64.bat
C:\Program Files\Microsoft Visual Studio 9.0\VC\vcvarsall.bat

Links and references:
NMAKE Reference (MSDN)
An introduction to Makefiles
Nmake Makefile Tutorial and Example
CL Environment Variables
LINK Environment Variables
Setting the Path and Environment Variables for Command-Line Builds

How to install IIS (7.5) on Windows Server 2008 R2

2011-09-21T14:33:00.001+01:00

1. Open Server Manager
2. Select Roles; right click -> Add Roles and Add Roles Wizard appears
3. In Add Roles Wizard: select Web Server (IIS) in Server Roles page and click Next
4. In Role Services page: select desired services (e.g. ISAPI extensions if IIS should host Axis2/C web service). Click Next.
5. Summary of role features and services that will be installed is displayed. Click Install.

Upon successful installation, a new node named Web Server (IIS) should appear under Roles in Server Manager.

No restart is needed and IIS service will start running automatically. To test whether IIS works, type http://localhost/ in your browser. IIS7 Welcome picture(png) should appear.

How to get processor architecture information on Windows

2011-09-21T13:22:00.001+01:00

Is your machine 32-bit or 64-bit?

One way of getting this information is reading PROCESSOR_ARCHITECTURE value which can be found in Windows Registry at this location: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment.

This value on my 32-bit Intel machine is x86 and on another 64-bit machine with Intel Xeon processor is AMD64.

64-bit vs 32-bit

2011-09-21T12:48:00.003+01:00

Processors, installed operating systems and applications can be 32-bit or 64-bit. OS needs processor support (64-bit OS requires 64-bit processor) and Application needs operating system support (64-bit application requires 64-bit OS). Backwards compatibility is preserved (32-bit OS runs on 64-bit processor; 32-bit application runs on 64-bit OS).

Here is a short review of all possible combinations:

		Operating System
		32	64
P r o c	32	OK	x	32	A p p
		x	x	64
	64	x	OK
		OK	OK	32

Backward compatibility is not preserved in kernel mode: 32-bit drivers won't work on 64-bit OS!

32-bit applications can run both on 32-bit and 64-bit operating systems. 64-bit Windows OS uses WoW64 emulation layer to support executing 32-bit applications which are, by default, installed in C:\Program Files (x86) directory, load 32-bit libraries from C:\Windows\SysWOW64 and use HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node portion of the registry.

64-bit applications can run only on 64-bit operating systems. It is possible to run 64-bit operating system on (physically) 32-bit machine (by using some of Virtual Machines, e.g. Oracle's VirtualBox).

It is possible to build applications that target 64-bit architectures on 32-bit hosts. This process is called cross-compiling.

DOS script which outputs directory contents into a txt file

2011-09-21T11:00:00.000+01:00

This simple batch file prints out (recursively, including subdirectories) the content of the current directory into a text file:

list_all_files.bat:

dir /b /s * >temp.txt

dir * lists the content of the current directory. /b switch makes it to use bare format (report does not include heading information or summary). /s instructs it to use recursion. >temp.txt instructs it to output report to temp.txt file.

After running it, this is the content of temp.txt:

C:\test\list_all_files.bat
C:\test\mydir
C:\test\temp.txt
C:\test\mydir\a.txt

Links and references:
Microsoft DOS dir command

Message only window (MFC)

2011-09-19T14:53:00.001+01:00

As expected: message only window cannot post messages to its "parent". CWnd::PostMessage() invoked on HWND_MESSAGE crashes with access violation:

class CMsgOnlyWnd : public CWnd
{
...
public:
Initialize();
SendMsgToParent();
...
}

CMsgOnlyWnd::Initialize()
{
...
CreateEx(0, ::AfxRegisterWndClass(NULL), "MsgOnlyWnd", 0, 0, 0, 0, 0, HWND_MESSAGE, 0, NULL);
...
}

CMsgOnlyWnd::SendMsgToParent()
{
GetParent()->PostMessage(...);
}

Links and references:
Message-Only Windows (MSDN)
How to make a Message Only Window
How to create a hidden window in C++